CAA Debugging Guide

CAA records are intentionally restrictive. Once you publish an applicable CAA record, every public CA that is not allowed by that policy should refuse issuance. That is the security benefit, but it also means certificate renewals can fail after a CA migration, wildcard change, DNSSEC problem, or inherited parent policy.

Use this guide when Let's Encrypt, cert-manager, certbot, lego, a hosting platform, or a commercial CA reports a CAA authorization problem.

Start with the Exact Certificate Request

Write down the names on the certificate and the CA doing the issuance.

Do not debug only the apex if the failed certificate is for a subdomain or wildcard.

Query CAA at the Name and Parents

Query the exact name first:

dig CAA www.example.com +short
dig CAA example.com +short

Then query the authoritative nameserver to bypass resolver cache:

dig @ns1.dnscale.eu CAA www.example.com +short
dig @ns1.dnscale.eu CAA example.com +short

If public resolvers and authoritative DNS disagree, wait for TTL expiry or investigate stale resolver cache:

dig @1.1.1.1 CAA www.example.com +short
dig @8.8.8.8 CAA www.example.com +short
dig @9.9.9.9 CAA www.example.com +short

If no CAA exists at the exact name, CAs walk up the DNS tree. A CAA record at example.com can control issuance for www.example.com, api.example.com, and deeper names unless a lower name publishes its own CAA RRset.

Match CAA Tags to the Certificate Type

For normal certificates, check issue:

example.com. 3600 IN CAA 0 issue "letsencrypt.org"

For wildcard certificates, check issuewild:

example.com. 3600 IN CAA 0 issuewild "letsencrypt.org"

Important behavior:

• If no issuewild records exist, wildcard checks can fall back to issue.
• If any issuewild record exists, wildcard issuance is controlled by issuewild.
• 0 issuewild ";" denies wildcard issuance from all public CAs.
• 0 issue ";" denies non-wildcard issuance from all public CAs.

A common failure is allowing Let's Encrypt with issue "letsencrypt.org" and later adding issuewild ";". That still allows normal certificates, but it blocks *.example.com renewals.

Verify the CA Identifier

CAA values are CA-specific identifiers, not always the marketing brand shown in a certificate UI. Verify the exact value with your CA's documentation before making policy strict.

Common values:

If a platform obtains certificates on your behalf, confirm which CA it actually uses. A hosting provider may switch between CAs over time, and the CAA policy must authorize the current issuer.

Check for Account-Bound Parameters

CAA can include parameters after the CA identifier. For example, some ACME deployments use account binding so only a specific ACME account may issue:

example.com. 3600 IN CAA 0 issue "letsencrypt.org; accounturi=https://acme-v02.api.letsencrypt.org/acme/acct/123456"

If an ACME account is rotated, recreated, or moved to a different environment, the CA identifier may still look correct while account-bound CAA blocks issuance. Compare the account URI in DNS with the account used by the current ACME client.

Check for CAA SERVFAIL and DNSSEC Problems

Certificate authorities need a reliable answer to the CAA lookup. If CAA queries return SERVFAIL, time out, or fail DNSSEC validation, the CA may refuse to issue even if the record content is correct.

dig @1.1.1.1 CAA example.com +dnssec
dig @1.1.1.1 CAA example.com +cd
dig +trace +dnssec CAA example.com

Interpretation:

If DNSSEC is involved, use DNSSEC Failure Troubleshooting before changing certificate automation.

Debug Subdomain Overrides

CAA inheritance stops when a CA finds a CAA RRset at the queried name. That means a subdomain can intentionally override the parent policy:

example.com.      3600 IN CAA 0 issue "letsencrypt.org"
shop.example.com. 3600 IN CAA 0 issue "digicert.com"

In that setup, shop.example.com authorizes DigiCert, not Let's Encrypt. If a renewal fails only for one subdomain, query that exact name before changing the apex.

Safe Fix Workflow

Use a narrow change first:

1. Confirm the actual issuer and certificate names.
2. Add the missing issue or issuewild value.
3. Keep existing authorized CAs until the new certificate has issued.
4. Wait for the CAA TTL to expire at public resolvers.
5. Retry issuance.
6. Remove old CA authorizations only after the migration is complete.

Avoid deleting every CAA record during an incident unless you are intentionally making issuance unrestricted. A safer emergency fix is usually adding the required CA temporarily, then tightening the policy after issuance succeeds.

DNScale CAA Examples

Allow Let's Encrypt for normal and wildcard certificates:

curl -X POST "https://api.dnscale.eu/v1/zones/{zone_id}/records" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "@",
    "type": "CAA",
    "content": "0 issue \"letsencrypt.org\"",
    "ttl": 3600
  }'
 
curl -X POST "https://api.dnscale.eu/v1/zones/{zone_id}/records" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "@",
    "type": "CAA",
    "content": "0 issuewild \"letsencrypt.org\"",
    "ttl": 3600
  }'

Add an incident-reporting address:

curl -X POST "https://api.dnscale.eu/v1/zones/{zone_id}/records" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "@",
    "type": "CAA",
    "content": "0 iodef \"mailto:security@example.com\"",
    "ttl": 3600
  }'

Related Guides

• DNS CAA Record Explained
• Let's Encrypt DNS-01 Challenges with DNScale
• cert-manager DNS-01 with DNScale
• DNSSEC Failure Troubleshooting
• SSL/TLS Certificates
• DNS Operations