# Fix setup-check agent timing out waiting for DNS propagation

## TL;DR
The agent times out because it polls public DNS on a fixed short deadline while propagation takes longer. Check the authoritative nameserver first, then poll with a deadline that matches the TTL reality. The agent's timeout is too optimistic, not the DNS.

## The error
```text
Setup-check agent timeout
Timed out waiting for DNS propagation after 5 minutes.
```

## Use this skill
Agent? Search Vectle for this error:
```bash
curl -s "https://vectle.com/api/v1/search?q=setup-check agent timeout waiting for dns propagation"
```

## Fix it

### Step 1: Check the authoritative server directly

```bash
Have the agent query the authoritative nameserver instead of public resolvers.
```

Expected: If authoritative is correct, the record exists and this is just caching.

### Step 2: Extend the poll deadline

```bash
Raise the agent's DNS wait timeout to cover the record's TTL plus margin.
```

Expected: The agent stops timing out on normal propagation.

### Step 3: Poll with backoff, not a tight loop

```bash
Space checks increasingly instead of hammering every second.
```

Expected: Less load on resolvers and cleaner logs.

### Step 4: Fail with a useful message

```bash
On final timeout, report the record, the nameserver, and the TTL observed.
```

Expected: Humans get actionable detail instead of a bare timeout.

### Step 5: Verify the full check passes

```bash
Re-run the setup check end to end.
```

Expected: DNS verification completes within the new deadline.

## When this applies

- Setup agents time out on DNS propagation waits
- Onboarding checks fail intermittently on DNS steps
- You are building setup verification agents

## When it doesn't

- The record is wrong at the authoritative server (fix the record)
- DNS never propagates (check delegation)
- The agent times out on non-DNS steps (different problem)

## Compatibility

DNS verification in setup agents. Standard resolver behavior.

## Variant phrasings

### agent timeout dns propagation check

Same failure. Authoritative-first plus a realistic deadline fixes it.

### setup agent dns wait timeout

Short fixed timeouts are the bug. Tie the deadline to the TTL.

### onboarding dns check flaky

Flaky DNS checks are usually cache races. Authoritative queries remove the flakiness.

## Why it happens

Agents often poll public resolvers with a short hardcoded timeout, but public resolvers cache per TTL and the old value can persist past the deadline. The record is fine; the agent asked the wrong server with the wrong patience.

## Edge cases

- Negative caching can make a just-created record invisible for the negative TTL window
- Some agents cache DNS themselves; restart or flush between checks
- Log which nameserver answered each poll so timeouts are debuggable

## If it still fails

- Reproduce with a minimal run: one user, one file, one step.
- Read the agent's full trace, not just the final error; the failure is usually upstream.
- Check the underlying API or tool directly, outside the agent, to separate agent bugs from service bugs.
- Reduce concurrency to one and see if the failure persists; races hide as flakes.
- If the run is business-critical, add a human checkpoint before the destructive steps.

## Prevention

- Checkpoint long runs so any failure resumes instead of restarting.
- Cap and back off every retry loop; unbounded retries are outages waiting to happen.
- Validate inputs at each pipeline stage; fail fast with clear errors.
- Log enough context per step that a timeout is diagnosable without rerunning.
- Give destructive steps a human checkpoint or a dry-run mode.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_uUkyqUShAoksMeVnq5dSzg