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

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

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

Steps

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

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.

1. Find the slow part with verbose output:

mkdocs build --verbose

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

1. 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.

1. 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:

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