Skip to main content

Manual DNS challenge

When CertAutoPilot cannot (or should not) automate your DNS provider — unsupported registrar, isolated network, change- management policy — use the manual DNS path. The backend computes the TXT record and shows it in the UI; you add it on your DNS side; you click Validate; the backend checks propagation and completes the ACME order.

When to use​

  • Your DNS provider is not one of the 18 supported providers and has no API at all.
  • Your change-management policy forbids automation writing to production DNS.
  • The zone is split-horizon or managed by a team that controls its own tooling.
  • You're issuing a one-off certificate with no intention to auto-renew.
Auto-renewal won't work

A manually-validated cert cannot auto-renew — the renewal workflow would need to publish a fresh TXT record 30 days from now, and there's nobody there to do it. Manual DNS is one-shot: Renew is rejected outright for these certificates (manual DNS certificates cannot be auto-renewed; re-issue instead), and auto-renew cannot be switched back on later. To refresh one, use Reissue and complete the manual TXT flow again — worth knowing before you reach for Renew near expiry.

Issue with manual DNS​

  1. Certificates → New.

  2. Configure issuer + subject + key type as usual.

  3. At the Validation step, toggle Manual DNS. Auto-renew turns off automatically.

  4. Submit. The backend opens an ACME order, receives the challenge tokens, and pauses the job in state awaiting_manual_dns.

  5. Open the certificate's detail page. The Manual DNS challenge panel lists one TXT record per identifier:

    Record name:  _acme-challenge.api.example.com
    Record type:  TXT
    Record value: "LoqXcYV8...WxKz"  (copied exactly as shown)
    TTL:          60 seconds recommended

  6. Publish each record on your DNS side.

  7. Verify propagation (recommended):

    dig +short TXT _acme-challenge.api.example.com @1.1.1.1

  8. Click Validate on the detail page. The backend runs a validate_manual_dns job, which asks the CA to verify and then waits for every authorization to go valid. It does not pre-check the TXT records itself — use the Check DNS button first if you want to confirm they are visible.

  9. On success the cert is issued. The job waits up to 3 minutes for the CA; past that it fails with authorization(s) not valid before timeout: <domains>. Fix the record and click Validate again — the ACME order stays usable.

Propagation tips​

  • Keep the TTL low (60 s) on the challenge record so your change reaches the CA quickly.
  • If your DNS has a long negative-caching TTL, resolvers may cache "no TXT record exists" from before your add. Wait at least that long.
  • Check multiple public resolvers: Cloudflare (1.1.1.1), Google (8.8.8.8), Quad9 (9.9.9.9) — the CA picks one of several.

Cleanup​

After issuance succeeds, the challenge records serve no purpose. You can delete them from the DNS side. The backend does not issue cleanup calls for manual DNS (it couldn't — no API credential) — deletion is on you. Leaving them in place causes no harm.

Multi-identifier certs​

A certificate with five SANs needs five TXT records (one per identifier). Wildcard identifiers (*.example.com) contribute a single TXT at _acme-challenge.example.com — validated against the apex. If a cert mixes example.com and *.example.com, the CA requires two separate TXT values at the same record name (use a multi-value TXT; most DNS providers accept an RRset with multiple strings).

Troubleshooting​

Check DNS says the record is not visible​

Propagation delay. Retry after a minute. If still absent after 5 minutes, confirm you added the record to the right zone — a domain at registrar.com may have delegated DNS elsewhere.

Check DNS shows a different value than expected​

Common cause: the record was saved with surrounding quotes stripped, or with line breaks. The UI's Copy button produces the exact value.

authorization(s) not valid before timeout​

The CA did not mark every authorization valid within the 3-minute wait — usually because the TXT record was not yet visible to the CA's resolvers when you clicked Validate. Confirm with Check DNS, then click Validate again; the ACME order stays valid for hours after a failed validation, so restarting usually works.

See also​