Adds troubleshooting guide for host missmatch error#2023
Adds troubleshooting guide for host missmatch error#2023epatmalnieks-gc wants to merge 1 commit into
Conversation
cert-manager-prow
Bot
added
the
dco-signoff: no
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
cert-manager-prow
Bot
added
the
size/XS
✅ Deploy Preview for cert-manager ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
epatmalnieks-gc
force-pushed
the
contribfest-epatmalnieks
branch
from
35581bd to
6a34733
Compare
cert-manager-prow
Bot
added
dco-signoff: yes
Signed-off-by: Edgars Patmalnieks <epatmalnieks@gocardless.com>
wallrj-cyberark
force-pushed
the
contribfest-epatmalnieks
branch
from
6a34733 to
9a2de01
Compare
There was a problem hiding this comment.
⚠️ Not ready to approve
The newly added troubleshooting text is currently misleading/inaccurate about what is mismatching and should be corrected to avoid sending users to the wrong remediation path.
Pull request overview
This PR adds troubleshooting guidance to the ACME troubleshooting documentation for the error ACME server URL host and ACME private key registration host differ, addressing the lack of documented remediation steps referenced in website issue #197.
Changes:
- Add a new “Common errors” bullet describing the ACME account host mismatch error and where to investigate.
File summaries
| File | Description |
|---|---|
| content/docs/troubleshooting/acme.md | Adds a new troubleshooting entry for the ACME account host mismatch error. |
Copilot's findings
- Files reviewed: 1/1 changed files
- Comments generated: 1
Note
Your feedback helps us improve the quality of this feature.
Please use 👍 or 👎 to tell us whether this assessment is correct.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| * `Failed to update ACME account:400 urn:ietf:params:acme:error:invalidEmail`: the email you specified in the Issuer configuration isn't valid. | ||
| * `Error initializing issuer: Failed to register ACME account: secrets "acme-key" already exists`: there might be a leftover account from a previous issuer that is no longer valid, you should remove the secret so it can be recreated. | ||
| * `Error accepting challenge: 400 urn:ietf:params:acme:error:malformed: Unable to update challenge :: authorization must be pending`: this suggests that the authorization was not in 'pending' state at a time when cert-manager sent a request to the ACME server to accept the challenge. This may be because the domain validation has already failed and the authorization has been marked as 'invalid'. Check the authorization URL on the status of the `Order` or `Challenge` to see the status of the authorization and any additional information. | ||
| * `ACME server URL host and ACME private key registration host differ` This error means that host resolved by the node differs from the host in your private key. Please check your `/etc/resolv.conf` if the correct host is resolved. |
wallrj-cyberark
left a comment
wallrj-cyberark
left a comment
There was a problem hiding this comment.
Thank you for addressing issue #197 — this documentation gap has been open for years and is worth filling. The Copilot review has independently flagged the same concerns below.
I checked the source code and found a few issues with the technical explanation.
1. This is not an error — it is an info-level log message.
The code at pkg/issuer/acme/setup.go:291 uses log.V(logf.InfoLevel).Info(...). When the condition triggers, cert-manager clears the cached account URI and re-checks the ACME registration. It is a self-healing action, not a failure.
2. The explanation of the cause is inaccurate.
The PR says "host resolved by the node differs from the host in your private key". The private key does not contain a host. What the code actually compares (line 290) is parsedAccountURL.Host (from issuer.status.acme.uri — the ACME account URL cached from a previous registration) against parsedServerURL.Host (from issuer.spec.acme.server — the configured ACME server URL).
Common causes include:
- Changing the ACME server URL (e.g. from staging to production)
- A stale
searchdomain in/etc/resolv.confcausing DNS to resolve the ACME server hostname differently (this is the scenario from cert-manager/cert-manager#3394) - Reusing a private key Secret from a different Issuer or cluster
3. Missing colon after the backtick-quoted message.
The existing bullet points all use the pattern `message`: explanation. The new entry is missing the colon separator.
A suggested replacement:
ACME server URL host and ACME private key registration host differ: this is an informational message (not an error) indicating that the host in the configured ACME server URL (spec.acme.server) differs from the host where the ACME account was previously registered (status.acme.uri). cert-manager will automatically clear the cached registration and re-check the account. Common causes include: changing the ACME server URL (e.g. from staging to production), a stalesearchdomain in/etc/resolv.conf(see cert-manager/cert-manager#3394), or reusing a private key Secret from a different Issuer. If the re-registration fails, check/etc/resolv.conffor incorrect search domains, or delete the private key Secret referenced by the Issuer to force a clean re-registration.
There is an open issue of missing troubleshooting info for
ACME server URL host and ACME private key registration host differThis issue is mentioned also on issue 3394This PR adds a simple description of the error and what would be the reasonable place to look for.