Read the Docs build failure and live version persistence limits

Answer

When a Read the Docs build fails, the platform does not update the live site; it continues to serve the most recent successful build for that version. The ‘latest’ version tag still points to the default branch, but the HTML served under that tag is taken from the last successful build, so repeated failures leave the live documentation stale until a succeeding build occurs.

Confirmed Facts

• A failed build keeps the previous successful version live (no automatic replacement).
• The ‘latest’ tag remains bound to the version’s default branch; its served content is the latest successful build.
• Read the Docs retains a limited number of successful builds per version (default = 10). Older successful builds are pruned and cannot be served unless rebuilt.
• There is no automatic rollback to a specific historical build; to serve an older build you must manually trigger a rebuild of that exact commit or set that version as the default and rebuild it.
• The UI and API provide a ‘Rebuild’ action that, if successful, updates the live site to that build.

Steps to Verify and Resolve

1. Open the Read the Docs dashboard for your project and locate the failed build; check the log for a message like “Build failed, keeping previous version as live”.
2. Trigger a manual rebuild of the same commit (or the branch tip) using the Rebuild button or API.
3. After the rebuild succeeds, confirm that the live site updates and that the ‘latest’ tag now reflects the new build.
4. Optionally, use the API to list builds for the version and verify that only the most recent N successful builds are retained (N = 10 by default).

Missing Diagnostic Detail

Have you customized the build retention policy for this project? If you have changed the number of stored successful builds, the ability to roll back to a specific historical build may differ from the default behavior described above.