Diagnosing Missing Versions in the Read the Docs Version Selector

Recognizable Condition

After pushing a commit to a repository connected to Read the Docs, a new version (such as a feature branch or a specific tag) does not appear in the version selector on the project dashboard, even though the build logs indicate a successful completion.

Diagnostic Summary

Possible Cause	What to Look For
Missing or incorrect readthedocs.yaml	The file is absent from the root or the version mapping points to a non-existent branch/tag.
Default branch name mismatch	The version name in the configuration does not match the repository's default branch (e.g., main vs master).
Version not activated	Build succeeded, but the version remains in an "inactive" state in the project settings.

Ordered Checks

1. Inspect the build log for the version

   In the Read the Docs dashboard, open the build page for the pushed commit. Verify that the log contains a line similar to Building version: <version-name> and ends with Build succeeded. If the log shows a different version name or skips the version step, note the discrepancy.

2. Check for readthedocs.yaml in the repository root

   Locally, run the following command from the repository root:

   ls -la readthedocs.yaml

   If the file is absent, it is a likely cause. If present, examine its contents for a version or branches section. A minimal correct configuration looks like this:

   version: 2
   
   branches:
     only:
       - main
       - feature/*

3. Validate default branch alignment

   Determine the repository's default branch (e.g., via GitHub Settings → Branches). Ensure the name used in readthedocs.yaml matches exactly. A mismatch (e.g., specifying master when the default is main) will cause the build to target a non-existent version.

4. Confirm version activation state

   Using the Read the Docs API (requires a personal token with read scope), check the status of the specific version:

   curl -s -H "Authorization: token YOUR_RTD_TOKEN" \\
     https://readthedocs.org/api/v2/projects/<PROJECT_SLUG>/versions/ | jq '.results[] | select(.identifier=="<VERSION_NAME>") | {identifier, active, built}'

   Replace <PROJECT_SLUG> and <VERSION_NAME>. If active is false despite built being true, the version was not activated.

Fixes Tied to Findings

When readthedocs.yaml is missing or incorrect

1. Add or edit readthedocs.yaml in the repository root.
2. Include a version directive set to 2 and a branches (or tags) section listing the desired versions.
3. Commit and push the change:

   git add readthedocs.yaml
   git commit -m "Add readthedocs.yaml for version selection"
   git push origin main

When default branch name mismatches

1. Update readthedocs.yaml to use the exact default branch name.
2. If the default branch was renamed (e.g., master to main), update all version mappings in the file.
3. Push the corrected file to the repository.

When the version is built but not active

1. In the Read the Docs dashboard, navigate to Versions for the project.
2. Locate the version entry and toggle the Active switch to on.
3. Trigger a rebuild via the API to ensure the active version serves the latest build:

   curl -X POST -H "Authorization: token YOUR_RTD_TOKEN" \\
     https://readthedocs.org/api/v2/projects/<PROJECT_SLUG>/versions/<VERSION_NAME>/build/

Verification Steps

1. Push a trivial commit (e.g., echo "test" >> README.md && git commit -am "trigger" && git push).
2. Watch the new build log to confirm the previously failing step now passes.
3. Check the version selector in the project UI to ensure the new version is listed and selectable.
4. Run the API verification command again to confirm "active": true.

Escalation Criteria

• If the version still does not appear after two consecutive builds following the fixes, collect the following:
• The Build ID from the dashboard URL.
• A snippet of the build log showing the version name and success status.
• The API output showing active and built flags.
• Open a support ticket with Read the Docs providing these details.

Limitations

• This guide assumes the default Read the Docs build environment. Custom build images or commands in .readthedocs.yml may affect version detection.
• If the repository enforces branch protection, versions will only appear after a Pull Request is merged and the resulting push triggers a build.
• Read the Docs enforces fair-use limits on concurrent builds; rapid pushes may cause builds to be queued, which can be mistaken for configuration failure.