Certbot DNS-01 Challenge TXT Record Mismatch on Alpine Linux

Troubleshoot Certbot DNS-01 TXT record mismatch on Alpine Linux. Learn why your ACME challenge fails and how to resolve common DNS propagation issues.

Certbot DNS-01 Challenge TXT Record Mismatch on Alpine Linux

When securing your web server with Let's Encrypt using Certbot, the DNS-01 challenge is often preferred for wildcard certificates or when port 80/443 is not directly accessible (e.g., behind a load balancer). This method requires you to prove ownership of your domain by adding a specific TXT record to your domain's DNS zone. A common issue, especially in production environments, is a mismatch between the TXT record Certbot expects and what it actually finds when verifying the challenge. This guide will walk you through diagnosing and resolving this "TXT records mismatch" error specifically on Alpine Linux systems.

Symptom & Error Signature

The most direct symptom is Certbot failing to obtain or renew a certificate, displaying an error message similar to the following in your terminal output:

Challenge failed for domain yourdomain.com
Challenge failed for domain www.yourdomain.com
tls-sni-01 and http-01 challenges did not work.
The following errors were reported by the server:

Domain: yourdomain.com
Type: unauthorized
Detail: The key authorization value specified in the DNS-01 challenge was expected to be "YOUR_EXPECTED_TXT_VALUE" but was "YOUR_OBSERVED_TXT_VALUE".
This often means that a TXT record for this domain was not correctly set. Please check the DNS record and ensure it is correct.

Hint: The Certificate Authority failed to verify the DNS TXT record for _acme-challenge.yourdomain.com.
Ensure that this record is in place and that it is published to the internet correctly.

If using a DNS plugin, you might also see:

Failed to install a certificate in the webserver, and an issue occurred during the verification of the certificate request.
Please check your logs for more information.

And in /var/log/letsencrypt/letsencrypt.log:

202X-XX-XX XX:XX:XX,XXX:DEBUG:acme.challenges:{"type": "dns-01", "token": "YOUR_TOKEN"}
202X-XX-XX XX:XX:XX,XXX:DEBUG:certbot.reporter:Reporting to user: The key authorization value specified in the DNS-01 challenge was expected to be "YOUR_EXPECTED_TXT_VALUE" but was "YOUR_OBSERVED_TXT_VALUE".

Root Cause Analysis

The "TXT records mismatch" error indicates that the ACME server (Let's Encrypt) could not find the exact TXT record it expected when it queried your domain's DNS. Several factors can contribute to this:

1. DNS Propagation Delays: This is the most common culprit. After you update a DNS record, it takes time for the changes to propagate across the internet's various DNS servers. If Certbot checks too soon, it might see an old or non-existent record.
2. Incorrect TXT Record Value:
   • Typo: A simple error in copying the long string Certbot provides.
   • Leading/Trailing Whitespace: Invisible characters can cause a mismatch.
   • Incorrect Format: Some DNS providers require quoting, others don't.
3. Incorrect TXT Record Name: The record must be named _acme-challenge.yourdomain.com (or _acme-challenge if your DNS provider automatically appends the base domain). Errors in the prefix or subdomain can lead to the record not being found.
4. Multiple TXT Records: If previous _acme-challenge records were not removed, or if multiple challenges are run concurrently, the ACME server might pick up an outdated or incorrect record from a set of valid ones.
5. DNS Provider Caching: Your local machine's DNS resolver or your DNS provider's internal caching might serve stale data even after the record is updated.
6. Certbot DNS Plugin Misconfiguration (if applicable): If you're using an automated Certbot DNS plugin (e.g., certbot-dns-cloudflare, certbot-dns-route53), an issue with API credentials, permissions, or rate limiting from the DNS provider can cause it to fail to set or verify the record correctly.
7. Firewall Restrictions: While less common for DNS, some restrictive firewalls might interfere with DNS queries, though this usually manifests as a timeout rather than a mismatch.
8. Alpine Linux Specifics: Alpine's minimalist nature means tools like dig are not installed by default, making manual verification slightly different initially.

Step-by-Step Resolution

Follow these steps to diagnose and resolve the Certbot DNS-01 TXT record mismatch error.

1. Understand the Expected TXT Record Value

First, carefully examine the Certbot error message. It explicitly states what TXT record value it expected to find. Make a note of this value and the full subdomain it was looking for (e.g., _acme-challenge.yourdomain.com).

Detail: The key authorization value specified in the DNS-01 challenge was expected to be "YOUR_EXPECTED_TXT_VALUE"

This YOUR_EXPECTED_TXT_VALUE is crucial.

2. Manually Verify the TXT Record at Public DNS Resolvers

It's essential to check what public DNS resolvers are seeing, not just your local cached results.

1. Install bind-tools on Alpine Linux: If you don't have dig (which is highly recommended for DNS troubleshooting), install it:

   sudo apk add bind-tools
   

2. Query your DNS record: Use dig to query authoritative and public DNS servers for the _acme-challenge TXT record for your domain. Replace yourdomain.com with your actual domain.

   # Query your domain's authoritative DNS servers
   dig TXT _acme-challenge.yourdomain.com +short
   
   # Query Google's public DNS (8.8.8.8)
   dig TXT _acme-challenge.yourdomain.com @8.8.8.8 +short
   
   # Query Cloudflare's public DNS (1.1.1.1)
   dig TXT _acme-challenge.yourdomain.com @1.1.1.1 +short
   

   Example Output:

   "YOUR_OBSERVED_TXT_VALUE"
   

   Compare the YOUR_OBSERVED_TXT_VALUE with YOUR_EXPECTED_TXT_VALUE from Certbot's error message. If they differ, or if no value is returned, you've found the problem.

   If dig returns multiple TXT records for _acme-challenge.yourdomain.com, this could also be the cause of the mismatch. Let's Encrypt expects a single, unambiguous record.

3. Correct the TXT Record at Your DNS Provider

Log in to your domain's DNS provider (e.g., Cloudflare, AWS Route 53, GoDaddy, Namecheap, etc.) and navigate to your DNS management zone.

1. Locate the _acme-challenge TXT record: Find the TXT record that Certbot is attempting to verify.
2. Ensure correct Name/Host:
   • The "Host" or "Name" field for the TXT record should be _acme-challenge. Some providers may require _acme-challenge.yourdomain.com explicitly, while others automatically append the base domain. If in doubt, try _acme-challenge first.
3. Ensure correct Value/Data:
   • The "Value" or "Data" field must exactly match the YOUR_EXPECTED_TXT_VALUE provided in Certbot's error message. No extra spaces, no missing characters, no quotes (unless your provider specifically requires them within the value field itself, which is rare).
4. Remove Duplicate or Stale Records:

   Ensure there is only one TXT record for _acme-challenge.yourdomain.com. If you find multiple, delete all but the most current one (or delete all and re-add the correct one). Stale records from previous failed attempts are a common source of this error.

5. Set a Low TTL (Time To Live):
   • Temporarily set the TTL for the _acme-challenge TXT record to a very low value, such as 60 or 120 seconds. This will speed up propagation of your changes. Remember to set it back to a higher value (e.g., 3600 seconds) after you've successfully obtained the certificate.

4. Wait for DNS Propagation

After making changes at your DNS provider, you must wait. Even with a low TTL, it can take a few minutes up to an hour or more for changes to propagate globally, especially if the old record was cached heavily.

• Continue using dig commands from Step 2, particularly querying @8.8.8.8 and @1.1.1.1, until you consistently see the YOUR_EXPECTED_TXT_VALUE in the output.
• You can also use online DNS checking tools like dnschecker.org or whatsmydns.net to verify global propagation.

5. Re-run Certbot

Once you've confirmed that the correct TXT record is visible globally via public DNS resolvers, you can re-run Certbot.

1. If using a manual challenge: Certbot will prompt you again to add the TXT record, but this time you've ensured it's correct.

   sudo certbot certonly --manual --preferred-challenges dns -d yourdomain.com -d *.yourdomain.com
   

2. If using a DNS plugin (recommended for automation): Certbot will attempt to set and verify the record automatically.

   # Example for Cloudflare plugin
   sudo certbot certonly --dns-cloudflare --dns-cloudflare-credentials /etc/letsencrypt/cloudflare.ini -d yourdomain.com -d *.yourdomain.com --email [email protected] --agree-tos --non-interactive
   
   # Test renewal (highly recommended)
   sudo certbot renew --dry-run
   

   Ensure your DNS plugin credentials file (/etc/letsencrypt/cloudflare.ini in the example) has the correct permissions (chmod 600) to prevent unauthorized access to your DNS API keys.

6. Alpine Linux Specific Considerations

• Certbot Installation: On Alpine, Certbot is typically installed via apk:

  sudo apk add py3-certbot
  # For Nginx integration:
  sudo apk add py3-certbot-nginx
  # For DNS plugins (example for Cloudflare):
  sudo apk add py3-certbot-dns-cloudflare
  

• Persistent Configuration: If you're running Certbot within a Docker container on Alpine, ensure that /etc/letsencrypt and any plugin credential files are mounted as persistent volumes so certificates and configurations are not lost on container restarts.

7. Review Certbot Logs for Further Clues

If the issue persists, review the Certbot logs located at /var/log/letsencrypt/ for more detailed information. The letsencrypt.log file can often provide specific errors reported by the ACME server or issues encountered by the DNS plugin.

sudo cat /var/log/letsencrypt/letsencrypt.log | tail -n 100

By following these steps, systematically verifying your DNS configuration, and allowing ample time for propagation, you should be able to resolve the Certbot DNS-01 challenge TXT record mismatch error on your Alpine Linux system.