docs agent's mkdocs build failed after it deleted the site_dir cache

Not specified by the original author.

TL;DR

Let MkDocs manage its own output directory: remove the agent's manual deletion and use mkdocs build --clean when you truly need a fresh build. Deleting site_dir while the build expects it breaks the run.

Error

Error: site_dir 'site' deleted by cleanup step; mkdocs build failed mid-run

Steps

1. Find the deletion in the agent's job: a cleanup step removing the site directory before or during the build. Expected: the conflicting step located.
2. Remove the manual deletion. MkDocs recreates and manages site_dir itself on every build. Expected: no external process touches the output dir.
3. If you need guaranteed-fresh output (stale files from renamed pages), use mkdocs build --clean, which empties the directory safely as part of the build. Expected: freshness without the race.
4. Re-run the pipeline. Expected: the build completes.

When to use

• The build fails after a cleanup step deleted the output dir
• A docs agent "cleans up" before building
• The failure mentions the site directory missing mid-build

When not to use

• The build fails for config or plugin reasons (unrelated to the directory)
• You want incremental builds (the default; just do not delete anything)
• The output dir is on a weird filesystem (check mounts and permissions)

Tool compatibility

MkDocs 1.4 through 1.6. The --clean flag behavior is stable.

Variant phrasings

agent deletes site_dir to "save space" between runs

The directory is small relative to the rebuild cost. Keep it, or clean on a schedule.

parallel jobs share one site_dir

Give each job its own output directory; concurrent builds into one dir corrupt each other.

Why it happens

Agents treat build output as temp files to tidy, but the builder treats the output dir as its workspace. Deleting it out from under the build is a race the build loses.

Provenance

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

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

Thread query: docs agent's mkdocs build failed after it deleted the site_dir cache

TL;DR: Let MkDocs manage its own output directory: remove the agent's manual deletion and use mkdocs build --clean when you truly need a fresh build. Deleting site_dir while the build expects it breaks the run.

Not specified by the original author.

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.

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

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:

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

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

Thread query: 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.

Not specified by the original author.

TL;DR

Stop doing full rebuilds: index only changed files, parallelize the workers, and give the step a longer timeout with retries. Full-corpus indexing grows with repo size, so on a large repo it will always eventually exceed a fixed timeout. Incremental indexing keeps each run roughly constant time.

docs agent failed: search index rebuild timed out on large repo

Steps

1. Measure the step: time the index rebuild on the full repo and compare against the agent's timeout. Expected: you get a number, so the fix is sized to reality instead of guessed.
2. Switch to incremental indexing: configure the search plugin to reindex only added, changed, or deleted files since the last build. Expected: the index step drops from minutes to seconds on typical runs.
3. Parallelize if the indexer supports workers: raise the worker count to match available CPUs. Expected: near-linear speedup on the unchanged full-rebuild path.
4. Raise the timeout and add a retry: set the agent's step timeout comfortably above the measured p95 build time, with one retry on timeout. Expected: transient slow runs pass instead of failing the whole docs job.
5. If the repo is huge even incrementally, move indexing out of the agent run: build the index in CI, store it as an artifact, and have the agent download it. Expected: the agent's docs step no longer indexes at all.

Use this when

• the docs search index step times out on large repos
• the built site has a stale or empty search index after agent runs
• index rebuild time grows with every release

Not for this skill when

• search is broken but the index builds fine (query or frontend bug)
• the whole docs build times out, not just indexing (build performance problem)
• the index is small and still slow (misconfiguration, not scale)

Variant phrasings

• docs search index build timed out
• search index rebuild too slow on monorepo
• agent timed out building docs search index

Why it happens

Full rebuilds re-read and re-tokenize every page on every run, so index time scales with total corpus size while the agent's timeout stays fixed. Large repos cross that line and the step dies at the same point every run, usually leaving a half-written index behind.

Edge cases

• A half-written index from a killed run can corrupt search: delete the partial index before retrying.
• Incremental indexes can drift if files change outside the watcher: run a full rebuild on a schedule (nightly or weekly) as a safety net.
• Raising the timeout without fixing the scaling just moves the failure to the next growth spurt.
• Some indexers hold the whole index in memory: watch memory, not just time, on very large corpora.

Provenance

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

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

Thread query: docs agent failed: search index rebuild timed out on large repo

TL;DR: Stop doing full rebuilds: index only changed files, parallelize the workers, and give the step a longer timeout with retries. Full-corpus indexing grows with repo size, so on a large repo it will always eventually exceed a fixed timeout. Incremental indexing keeps each run roughly constant time.