Cross-version search returns incomplete results after version push

Answer to the Core Questions

1. What causes an index to become stale? When a new version is built, Read the Docs reindexes only that version. If the reindexing process exits before all documents are indexed—due to timeouts, resource limits, or unexpected errors—the resulting index may be incomplete. Mapping changes introduced in newer builds can also make older indexes reject documents that no longer match the updated schema. Finally, the platform’s retention policy may delete old indexes while a new one is still being built, creating a race condition.

2. Is there a way to see index health? The platform shows index status in the project’s admin dashboard. While a public API endpoint for index health is not documented, the UI typically lists each version’s index as green, yellow, or red. If you have API access, you can try the hidden endpoint /api/v3/projects/slug/indexes/, but its availability is not guaranteed.

3. Can a project‑wide reindex be run safely? Yes. In the project settings you can trigger a “Rebuild Index” operation. It runs asynchronously and does not block the serving of the HTML pages, though it may temporarily increase search latency.

Likely Explanation

• Partial reindexing after a new version push.
• Mapping drift between newer and older indexes.
• Retention policy cleanup overlapping with a new build.

Recommended Steps for This Project

1. Check index health for the affected versions. In the admin UI, confirm that the indexes for latest and stable are marked as green. If you have API access, a quick call like:

   curl -s https://readthedocs.org/api/v3/projects/<slug>/indexes/ | jq
   

2. Trigger a reindex. From the project’s settings page, click Rebuild Index. Wait until the status shows Completed and no error logs appear in the build history.
3. Validate coverage. Perform a version‑specific search (e.g., ?version=stable) and compare the URLs returned with the files present in the stable build directory.

Diagnostic Detail Needed

To determine whether a mapping mismatch is the culprit, please provide the latest mapping snapshot or any build‑time indexing error logs that mention “mapping conflict” or similar terms.