# Fix DNS propagation stuck during new domain onboarding

## TL;DR
Propagation that seems stuck is usually a wrong record or a cached old value, not slow DNS. Check the record with dig against the authoritative nameserver first; if it is wrong there, fix it. Only then blame caching, and lower the TTL for the next change.

## The error
```text
DNS propagation stuck
New domain records not visible after many hours. Onboarding blocked.
```

## Use this skill
Agent? Search Vectle for this error:
```bash
curl -s "https://vectle.com/api/v1/search?q=dns propagation stuck new domain onboarding"
```

## Fix it

### Step 1: Query the authoritative nameserver directly

```bash
dig @[nameserver] [record] [type] for the record in question.
```

Expected: If the authoritative server shows the wrong value, the record itself is wrong. Fix it there.

### Step 2: Check public resolvers

```bash
Query a couple of public resolvers and compare.
```

Expected: If they differ from authoritative, you are seeing cache; note the remaining TTL.

### Step 3: Fix the record if wrong

```bash
Correct the value at your DNS provider.
```

Expected: Authoritative answers are now correct.

### Step 4: Wait out the TTL or flush where you can

```bash
Wait for the old TTL to expire; flush local and OS caches in the meantime.
```

Expected: Resolvers converge on the new value as TTLs expire.

### Step 5: Lower TTLs before the next change

```bash
Drop the TTL to a few minutes well ahead of future changes.
```

Expected: The next change propagates in minutes, not hours.

## When this applies

- New domain DNS changes seem stuck for hours
- Onboarding is blocked waiting on DNS
- You are cutting a domain over to new infrastructure

## When it doesn't

- The authoritative server is correct and resolvers agree (the problem is elsewhere)
- The domain does not resolve at all (check delegation and nameservers)
- Only one network sees the old value (that network caches aggressively)

## Compatibility

DNS generally. dig and standard resolver behavior.

## Variant phrasings

### dns not propagating new domain

Same troubleshooting. Authoritative first, then caches.

### dns changes taking too long

Too long usually means a high TTL was set before the change. Lower TTLs ahead of changes.

### domain onboarding dns stuck

Onboarding checklists that wait on DNS should verify against authoritative servers, not public ones.

## Why it happens

DNS has two layers: what you published (authoritative) and what resolvers remember (cache). Most stuck propagation is actually a wrong authoritative record, and the rest is resolvers honoring a long TTL you set before the change. True propagation delay beyond TTL expiry is rare.

## Edge cases

- Some ISP resolvers ignore TTLs and cache longer; you cannot fix their behavior
- Negative caching means a queried-missing record stays missing for the negative TTL
- Changing nameservers themselves takes the longest; plan those moves carefully

## 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_nh1Qf48eqrN3u998rwAbZw