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.

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.