Troubleshooting · 15.2
DNS-01
With DNS-01, TLSPilot creates a TXT record _acme-challenge.<name> with the DNS provider, waits for propagation, lets the CA validate it and deletes it again. Errors of the DNS provider are shown with the HTTP status and the answer of the provider, for example Cloudflare create TXT failed: <status> <answer>.
| Symptom | Cause | Solution |
|---|---|---|
| All providers | ||
| DNS-01 for <certificate> is incomplete: Provider and Credential are required. | No DNS provider or no credential is selected in the step Settings of the certificate. | Select the DNS provider and the DNS credential, see chapter ACME certificate (AC). |
| Status bar DNS-01 waiting <n>s for propagation, then Authorization invalid for <name> with One validator did not see the TXT yet (NXDOMAIN). | The CA validates from several locations, see chapter Multi-perspective validation; one of them did not see the TXT record yet. | Click Force renew… again, or raise DNS-01 propagation wait (seconds, 15-300) in the settings on the tab ACME providers (default 60), for example to 90–120. |
| DNS-01: public NS of the domain must match the DNS provider; check TXT with nslookup 8.8.8.8. | The TXT record was created at a provider that is not authoritative for the domain. | Check the public name servers of the domain and the TXT record with nslookup -type=TXT _acme-challenge.<name> 8.8.8.8. |
| Log: Public DoH poll did not yet see TXT <record> … Proceeding to Let’s Encrypt validation anyway | After the wait, the TXT record was not yet visible at the public resolvers of Cloudflare and Google. The check is advisory only; TLSPilot continues with the validation. | No action if the certificate is issued. If the validation then fails, raise DNS-01 propagation wait (seconds, 15-300). |
| The validation fails at some attempts only, although the TXT record is visible at the DNS provider | Not all authoritative nameservers deliver the TXT record yet, for example because a secondary nameserver is updated later. Every network perspective of the CA can ask another nameserver, see chapter Multi-perspective validation. | List the nameservers with dig NS <zone> +short and query each one: dig @<nameserver> TXT _acme-challenge.<name> +short. Raise DNS-01 propagation wait (seconds, 15-300) until all of them answer. |
| The validation fails although the TXT record is visible at some locations | Geo-DNS or traffic steering at the DNS provider answers differently depending on the location of the query. | Exclude _acme-challenge names from location-based rules, so that every location gets the same TXT record. |
| The TXT record is visible on the management host or in the internal network, but the validation fails | Split DNS: internal resolvers answer from an internal zone. The CA only sees the public zone. | Create the record at the DNS provider of the public zone and check it with a public resolver, for example dig @8.8.8.8 TXT _acme-challenge.<name>. |
| <Provider> zone <zone> not found. | The account behind the credential does not manage this zone, or the zone name is wrong. | Check the zone at the provider and the permissions of the API token or key. |
| Providers with an API token (Cloudflare, Hetzner, DigitalOcean, Linode, deSEC, Hostinger) | ||
| <Provider> credential <name> not found, for example DigitalOcean credential … not found (password=API token). | The DNS credential does not exist or has no token as secret. | Create the credential with the API token as secret in the Credentials Manager. |
| Hetzner: Hetzner zone id was not found in the Cloud API. Select the zone again. | HTTP 404: the certificate stores a zone id of the Hetzner DNS Console. | Select the zone again in the certificate. TLSPilot resolves the zone by its name. |
| Hetzner: Hetzner Cloud API rejected the token (<status>). with a request for a new Hetzner Cloud API token | HTTP 401 or 403: the token is not a Hetzner Cloud API token or is not valid. Tokens of the Hetzner DNS Console do not work. | Create a Hetzner Cloud API token in the Hetzner Console. Until then, use DNS Manual, see chapter Manual DNS validation. |
| Hostinger: Hostinger rejected a zone overwrite (DNS:4008). TLSPilot never sends overwrite=true. | The provider refused the change of the zone. | Check the zone at Hostinger and try again. |
| Providers with key and secret (Route 53, GoDaddy, Porkbun, OVH, Namecheap, ClouDNS) | ||
| Route 53: Route 53 ListResourceRecordSets was denied (<detail>). UPSERT writes only this TXT value. | The IAM policy lacks route53:ListResourceRecordSets. TLSPilot then replaces the whole TXT set at the name with the challenge value, so other values at the same name are lost. | Grant route53:ChangeResourceRecordSets, route53:ListHostedZones and route53:ListResourceRecordSets. |
| Route 53 credential … missing. UserName=Access Key Id, Secret=Secret Access Key. Similar for GoDaddy (API Key, API Secret) and Porkbun (API key, Secret key). | The credential does not contain both values. | Store the key as user name and the secret as secret of the credential. |
| OVH: OVH UserName must be ApplicationKey:ApplicationSecret:ConsumerKey. | The OVH credential has the wrong format. | Enter Application Key, Application Secret and Consumer Key as described in the message. |
| Namecheap: The Namecheap API Client IP allow-list is mandatory. | Namecheap only accepts API calls from allowed IP addresses. | Add the public IP address of the management host under Namecheap Profile → Tools → API Access. |
| ClouDNS: ClouDNS authentication failed. or ClouDNS auth-id must be a number (API User ID) | The login user name was used instead of the numeric auth-id. | Use the numeric auth-id as user name and the auth-password as secret (API & Resellers → API Users). |
| Cloud DNS with a service principal or service account (Azure DNS, Google Cloud DNS) | ||
| Azure credential … not found (UserName=appId, Password=client secret or PEM certificate). or Azure DNS put TXT failed: <status> | The app registration is missing, or it may not change the DNS zone. | Store the appId as user name and the client secret or PEM certificate as secret. Grant the app registration write access to the DNS zone. |
| Google Cloud DNS credential secret must be a service-account JSON key (client_email + private_key). or No Google Cloud DNS managed zone in project … matches … | The secret is not a service-account JSON key, or the project contains no matching zone. | Store the JSON key of the service account as secret and check the GCP project of the zone. |
| RFC 2136 and DNS Manual | ||
| BIND nsupdate not found. Install BIND tools or set Dns01.Settings nsupdatePath to the nsupdate executable. | RFC 2136 uses nsupdate from the BIND tools, which is not installed. | Install the BIND tools on the management host or set the path to nsupdate. |
| RFC2136 credential … not found (UserName=TSIG key name, Password=secret). or nsupdate failed (<code>) | The TSIG key is missing or does not match the name server. | Store the TSIG key name as user name and the key as secret, and check the name server address. |
| DNS Manual: waiting for DNS TXT | No error. The order waits until you have created the TXT record. | Create the TXT record shown and continue, see chapter Manual DNS validation. |
| DNS-01 Alias Mode | ||
| The order does not start: DNS-01 Alias Mode: CNAME _acme-challenge.<name> is missing. It must point at <target>. Fresh CNAMEs can stay hidden for a few minutes because of negative caching. | The CNAME record has not been created in the production zone, or a resolver caches the negative answer from the time before it was created. | Create the CNAME record exactly as listed below Alias domain, check it with Check CNAMEs or dig +short CNAME _acme-challenge.<name>, and wait a few minutes if it was just created, see chapter Set up DNS-01 Alias Mode. |
| The order does not start: … CNAME _acme-challenge.<name> points at <other name>, expected <target>. | The CNAME record points to another name, for example without the name of the certificate, to another alias domain or with a typing error. | Correct the target to _acme-challenge.<name>.<alias domain> as listed in the certificate, and check that Alias domain is the zone at the DNS provider. |
| The order does not start: … CNAME _acme-challenge.<name> has a TXT record at the same name. Remove it before the order. or … has more than one CNAME. Keep a single CNAME to <target>. | A TXT record, for example from an earlier validation, or a second CNAME record exists at the same name. A name with a CNAME record must not have any other records. | Delete the TXT record or the additional CNAME record at _acme-challenge.<name> in the production zone, so that only the one CNAME record remains. |
| Warning, the order starts nevertheless: … CNAME _acme-challenge.<name> could not check. No DNS-over-HTTPS resolver answered. | Neither cloudflare-dns.com nor dns.google answered, for example because a firewall or proxy blocks outbound HTTPS from the management host. This does not mean that the CNAME record is missing. | Allow outbound HTTPS (TCP 443) from the management host to cloudflare-dns.com and dns.google, then click Check CNAMEs. If the validation fails, check the CNAME records with dig. |
| The CNAME records are correct, but the validation fails with SERVFAIL or a DNSSEC error | DNSSEC is switched on in the alias zone or in the production zone, and the signature of the chain over the CNAME and the TXT record is broken, for example because of a missing or outdated DS record. | Check the DNSSEC signature of both zones, for example with a DNSSEC analyzer, and correct the DS record at the registrar or switch DNSSEC off in the alias zone, see chapter DNS-01 challenge delegation (CNAME alias). |