docs agent failed: readthedocs webhook fired the build before the p

Not specified by the original author.

TL;DR

Make the build wait for the push to be visible: enable the webhook retry or add a short delay before the RTD build starts. The webhook can arrive before the hosting provider serves the new commits.

Error

(build triggered for commit abc123; RTD checked out the previous commit; docs stale after push)

Steps

1. Confirm the race: compare the commit RTD built against the pushed commit. Expected: RTD built the older one.
2. In the Read the Docs project settings, check the webhook and build settings for retry or sync options; re-trigger the build manually once to confirm the push content builds fine. Expected: manual rebuild produces correct docs.
3. Add a delay or a poll-for-commit step between push and build trigger in the agent's pipeline (poll the hosting API until the commit is listed). Expected: the build only starts when the commit is fetchable.
4. Re-run the push-to-publish flow. Expected: the automated build uses the new commit.

When to use

• RTD builds stale content right after a push
• A docs agent pushes and immediately triggers the build
• Manual rebuilds fix what automated builds got wrong

When not to use

• RTD fails on dependencies or config (unrelated to timing)
• The webhook never fires (a webhook configuration problem)
• The built commit is right but content is wrong (a source problem)

Tool compatibility

Read the Docs with GitHub/GitLab/Bitbucket webhooks. The race is host-independent.

Variant phrasings

intermittent stale builds

The race only triggers under load or replication lag. The poll-for-commit step fixes it deterministically.

agent triggers via API instead of webhook

Same fix: poll until the commit is visible before calling the build API.

Why it happens

Webhooks fire on push receipt, but the new objects may not be readable from all replicas yet. A build that clones immediately can fetch the pre-push state.

Provenance

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

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

Thread query: docs agent failed: readthedocs webhook fired the build before the push landed

TL;DR: Make the build wait for the push to be visible: enable the webhook retry or add a short delay before the RTD build starts. The webhook can arrive before the hosting provider serves the new commits.

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.

Not specified by the original author.

TL;DR

Roll back production to the last good deploy first, then move all draft work to preview or staging deploys behind an explicit promote step. The agent published drafts because nothing distinguished a draft deploy from a production one. Rollback stops the bleeding; the promote gate stops the repeat.

docs agent failed: published draft docs to production site

Steps

1. Confirm production is serving drafts: open the live site and look for draft banners, unreviewed pages, or placeholder text. Note which deploy introduced it from your hosting dashboard's deploy history.
2. Roll back: redeploy the previous production build (most hosts let you pick a prior deploy and promote it, or rerun the production pipeline on the last good commit). Expected: the live site serves the previous content; spot-check two or three pages.
3. Verify the rollback took: fetch the live URL for a page that had draft content and confirm the draft is gone. Expected: no draft markers anywhere on the production site.
4. Move drafts to preview deploys: configure the agent so every docs change builds to a preview URL by default, never to production. Expected: the agent's next run produces a preview link.
5. Add the promote gate: production deploys only happen through an explicit step (a manual promote button, a tag, or a CI job that only runs on release branches). The agent is not allowed to trigger it. Expected: a dry run of the agent's normal flow produces a preview link, not a production deploy.

Use this when

• the live docs site shows draft or unreviewed content
• an agent deploy overwrote production docs unexpectedly
• you need to separate draft previews from the production site

Not for this skill when

• production content is wrong but was reviewed and merged on purpose (content bug, not a deploy bug)
• the deploy failed outright (build error instead)
• you want faster production deploys (this skill adds a gate, not speed)

Variant phrasings

• agent deployed unfinished docs to production
• draft docs went live by accident
• docs agent published to the prod site instead of staging

Why it happens

The agent had one deploy command and no notion of environments, so "deploy the docs" meant production. Drafts and releases shared the same pipeline, and nothing required a human or an explicit promote action before the public site changed.

Edge cases

• Cached pages can keep serving drafts after rollback: purge the CDN or hosting cache for the affected paths.
• Search engines may have indexed draft URLs: remove them via your search console after rollback.
• If the bad deploy also changed redirects or config, roll those back too, not just the content.
• Preview URLs sometimes leak into sitemaps: keep previews out of the production sitemap.

Provenance

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

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

Thread query: docs agent failed: published draft docs to production site

TL;DR: Roll back production to the last good deploy first, then move all draft work to preview or staging deploys behind an explicit promote step. The agent published drafts because nothing distinguished a draft deploy from a production one. Rollback stops the bleeding; the promote gate stops the repeat.