# Fix LetsEncrypt DNS-01 challenge failing

## TL;DR
DNS-01 fails when the _acme-challenge TXT record is missing, wrong, or invisible. Create the exact TXT record the ACME client requests, confirm it with dig, then let the client continue. Automate this with your DNS provider's API so it never depends on manual steps.

## The error
```text
LetsEncrypt DNS-01 challenge failed
DNS problem: NXDOMAIN looking up TXT for _acme-challenge.[domain]
```

## Use this skill
Agent? Search Vectle for this error:
```bash
curl -s "https://vectle.com/api/v1/search?q=letsencrypt dns-01 challenge failed"
```

## Fix it

### Step 1: Get the exact challenge value

```bash
Run your ACME client in manual or hook mode and copy the TXT value it requests.
```

Expected: You have the exact value for _acme-challenge.[domain].

### Step 2: Create the TXT record

```bash
Add the TXT record at _acme-challenge.[domain] in your DNS.
```

Expected: The record exists in your zone.

### Step 3: Confirm with dig before continuing

```bash
dig TXT _acme-challenge.[domain] and check the value matches.
```

Expected: The record is publicly visible with the right value.

### Step 4: Let the ACME client verify

```bash
Continue the ACME flow so LetsEncrypt checks the record.
```

Expected: The challenge passes and the certificate issues.

### Step 5: Automate with a DNS hook

```bash
Configure your ACME client with your DNS provider's API for automatic challenge records.
```

Expected: Renewals create and clean up the TXT records with no manual steps.

## When this applies

- LetsEncrypt DNS-01 challenges fail
- Wildcard certificates will not issue
- You are automating certificate renewals

## When it doesn't

- HTTP-01 challenges fail (different challenge type)
- The challenge passes but issuance fails (check rate limits)
- Your DNS provider has no API (use manual mode or switch providers)

## Compatibility

LetsEncrypt ACME DNS-01. Certbot and other ACME clients.

## Variant phrasings

### letsencrypt dns challenge txt not found

Same failure. The TXT record name or value is wrong, or DNS has not published it.

### acme dns-01 nxdomain

NXDOMAIN means the record name does not exist. Check for typos in _acme-challenge.

### certbot dns-01 challenge failed

Certbot manual mode waits for you; automated hooks do it for you. Prefer hooks.

## Why it happens

DNS-01 proves domain control by asking you to publish a specific TXT record. LetsEncrypt queries public DNS for it; if the record is missing, has the wrong value, or sits at the wrong name, the challenge fails. Manual processes also race the client's timeout.

## Edge cases

- Multiple challenges in flight overwrite each other's TXT values; run them serially or use distinct hooks
- CNAME-following for _acme-challenge lets you delegate challenges to a dedicated zone
- LetsEncrypt rate limits punish repeated failures; get the record right before retrying hard

## If it still fails

- Verify from multiple networks; one network's cache is not the internet's state.
- Check the domain's delegation and nameservers before blaming individual records.
- Wait out one full TTL after a fix before declaring it still broken.
- Keep a known-good dig output to diff against during the next incident.
- If a provider's verification never passes with correct records, escalate with dig output and timestamps.

## Prevention

- Lower TTLs a day before any planned DNS change.
- Verify every record with dig against authoritative before declaring done.
- Monitor certificate and domain expiry with alerts, not memory.
- Keep DNS change history; most outages are a bad edit, not propagation.
- Test verification flows in staging with a throwaway subdomain.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_-z6TYH2txoOZF1f5lSfZpA