# Fix onboarding agent timeout during domain verification DNS lookup

## TL;DR
The agent times out on the DNS lookup because it uses a short deadline against slow or cached resolvers. Query the authoritative nameserver with a realistic timeout and retry with backoff. The lookup is slow, not broken.

## The error
```text
Onboarding agent timeout
Timed out during domain verification DNS lookup.
```

## Use this skill
Agent? Search Vectle for this error:
```bash
curl -s "https://vectle.com/api/v1/search?q=onboarding agent timeout during domain verification dns lookup"
```

## Fix it

### Step 1: Query authoritative directly

```bash
Point the lookup at the domain's authoritative nameserver.
```

Expected: You get the true record state fast.

### Step 2: Extend the lookup timeout

```bash
Raise the DNS timeout to handle slow resolvers.
```

Expected: Lookups stop timing out spuriously.

### Step 3: Retry with backoff

```bash
On timeout, retry a few times with growing delays.
```

Expected: Transient resolver slowness clears.

### Step 4: Cache the result for the run

```bash
Once verified, reuse the result instead of re-querying.
```

Expected: No repeated lookups for the same domain.

### Step 5: Verify the check passes

```bash
Re-run the domain verification step.
```

Expected: It completes within the new deadline.

## When this applies

- Agents time out on domain verification DNS lookups
- Verification steps are flaky on DNS
- You are building domain verification agents

## When it doesn't

- The record is wrong (fix the DNS record)
- The domain does not exist (check the domain)
- Lookups fail instantly (check network access)

## Compatibility

DNS lookups in verification agents. Standard resolver behavior.

## Variant phrasings

### agent dns lookup timeout verification

Same failure. Authoritative queries plus realistic timeouts fix it.

### domain verification dns slow agent

Slow resolvers are common. Backoff and caching handle them.

### onboarding dns check timeout

Timeouts on checks usually mean the check's deadline, not the DNS, is wrong.

## Why it happens

Public resolvers can be slow or serve stale cache, and agents with short DNS timeouts give up before getting an answer. The verification logic is fine; the network patience is not.

## Edge cases

- Some networks intercept DNS; the agent may need the network's resolver, not a public one
- IPv6-only or IPv4-only networks break lookups that assume both; match the network
- Log the resolver used and the latency so slow lookups are visible

## 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_RD3-DhCgOePe5H2pUSw33w