# docs agent failed: timed out waiting for mkdocs build to finish

## TL;DR
Give the build more time, then make the build faster: raise the agent's subprocess timeout to a multiple of the measured build time and trim the slowest plugins. Large sites with search or macro plugins can take minutes, which trips a default 60 to 120 second agent timeout. Measure first, then tune.

## The error

```text
docs agent failed: timed out waiting for mkdocs build to finish
```

## Steps

1. Time the build yourself to get the real number:

```text
time mkdocs build
```

Expected: you get a wall-clock duration to compare against the agent's timeout. If the build takes 4 minutes and the agent waits 2, you found it.

2. Find the slow part with verbose output:

```text
mkdocs build --verbose
```

Expected: you can name the slowest plugin step. Usual suspects are the search index on huge sites and macro/template plugins.

3. Raise the agent's wait. Set its subprocess timeout to 2 to 3 times the measured build time, and make it wait for process exit rather than a fixed sleep.

Expected: the agent no longer kills a healthy build that just needs time.

4. Trim build cost for agent runs. Keep a second config for automation (for example mkdocs-agent.yml) that disables the slowest plugin, and run the agent against it:

```text
mkdocs build -f mkdocs-agent.yml
```

Expected: build time drops measurably and the full plugin set still runs in the normal CI job.

## Use this when

- the agent kills mkdocs build on timeout but the build passes when run by hand
- the site is large and the build legitimately takes several minutes
- timeouts started after adding a new plugin or a batch of new pages

## Not for this skill when

- mkdocs build fails with an actual error instead of timing out
- the build hangs forever even when run by hand (that is a real hang, investigate the plugin)
- the timeout hits a different tool like docusaurus or sphinx

## Variant phrasings

### mkdocs build killed after timeout in CI agent
Same fix: measure, raise the timeout, trim plugins for the agent profile.

### agent subprocess timeout too short for docs build
Check whether the timeout is per-command or per-session; per-command is what the build needs.

### mkdocs build slow after adding plugins
Profile with --verbose before raising timeouts; sometimes one plugin is the whole problem.

## Why it happens
Agent harnesses default to short subprocess timeouts built for quick commands. MkDocs builds are single-threaded and plugin-bound, so big sites legitimately need minutes. The agent mistakes a slow-but-healthy build for a stuck one and kills it.

## Edge cases

- A plugin can hang on one malformed page rather than just be slow. If the same page always stalls, bisect by excluding directories until the stall disappears.
- A full or read-only filesystem in the sandbox slows builds to a crawl. Check disk space before blaming plugins.
- With --strict, warnings become failures and buffered output can look like a hang. Read the warnings first.
- Incremental rebuilds do not apply to mkdocs build; do not expect a second run to be faster.

## Provenance

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