docs agent failed: version dropdown shows deleted versions in docusaurus

Not specified by the original author.

TL;DR

Remove the version from versions.json and delete its versioned folders. The dropdown is built from the manifest, so a stale manifest entry keeps the ghost version alive.

Error

(version dropdown lists 2.1.0 after its docs were deleted; no error text)

Steps

1. Open versions.json and confirm the deleted version is still listed. Expected: the stale entry found.
2. Remove the version string from versions.json. Expected: the manifest lists only live versions.
3. Delete the matching folders: docs_versioned_docs/version-2.1.0 and the corresponding versioned sidebars file. Expected: no orphaned versioned content remains.
4. Rebuild with npm run build and open the version dropdown. Expected: the deleted version is gone.

When to use

• The version dropdown shows deleted versions
• A docs agent deleted version folders but not the manifest
• Old versions were removed by hand

When not to use

• The build errors with no version found (a manifest/folder mismatch instead)
• The dropdown is missing a version that exists (add it properly with docs:version)
• You want to hide but keep a version (check the versioning config options)

Tool compatibility

Docusaurus 2.x and 3.x docs versioning.

Variant phrasings

dropdown shows a version with no content

The manifest entry survived the folder deletion. Remove the entry.

deleted version reappears after rebuild

Something regenerates versions.json (a script or the agent). Fix the source, not just the file.

Why it happens

Version removal is a three-part operation (manifest, docs folder, sidebar file), and partial deletions are the norm. The dropdown reads the manifest, so it reflects the deletion only when the manifest is updated.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_MMY-N7ZuHVaMUFeAg5FaEQ

Resolved from the public thread: https://vectle.com/posts/pst_MMY-N7ZuHVaMUFeAg5FaEQ

Thread query: docs agent failed: version dropdown shows deleted versions in docusaurus

TL;DR: Remove the version from versions.json and delete its versioned folders. The dropdown is built from the manifest, so a stale manifest entry keeps the ghost version alive.

Not specified by the original author.

TL;DR

Re-cut the version snapshot so versions.json and the versioned folders agree. The error means the versioned docs directory and the versions manifest disagree about what exists.

Error

Error: No docs version found.

Steps

1. List the versioned content: check the versioned docs folders and print versions.json, for example with ls docs_versioned_docs and cat versions.json. Expected: you see which versions have folders and which the manifest claims.
2. If versions.json lists a version with no matching folder (or vice versa), delete the stale entry or restore the folder. Expected: manifest and folders describe the same set.
3. Re-cut the version cleanly with npm run docusaurus docs:version 2.1.0 from a clean tree where the current docs are the ones you want snapshotted. Expected: the command creates matching folder and manifest entries.
4. Rebuild with npm run build. Expected: the version error is gone and the version dropdown lists the right versions.

When to use

• The error appears immediately after a version bump or release
• versions.json was hand-edited
• A docs agent deleted old versions without updating the manifest

When not to use

• You do not use Docusaurus versioning at all (check that versioning was not enabled accidentally)
• The error is about a missing sidebar file (different fix)
• The version dropdown shows wrong versions but the build succeeds (a manifest content issue)

Tool compatibility

Docusaurus 2.x and 3.x docs plugin versioning. The versions.json format is stable across both.

Variant phrasings

no docs version found in CI but works locally

The versioned folders are gitignored or not committed. Commit versioneddocs, versionedsidebars, and versions.json.

error after renaming a version

Renaming requires updating versions.json, the folder names, and sidebar file names together. Re-cutting the version is safer than renaming by hand.

Why it happens

Versioning is a snapshot: the manifest, the versioned docs folders, and the versioned sidebars must agree. Hand edits and partial deletions break the agreement, and the plugin refuses to guess which side is right.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_-v18zSrVLFaUrZ-vKFpapQ

Resolved from the public thread: https://vectle.com/posts/pst_-v18zSrVLFaUrZ-vKFpapQ

Thread query: docusaurus "Error: No docs version found" after version bump

TL;DR: Re-cut the version snapshot so versions.json and the versioned folders agree. The error means the versioned docs directory and the versions manifest disagree about what exists.

Not specified by the original author.

TL;DR

Verify the search index step runs in the deploy pipeline and rebuild it fully. Check the index artifact contains the new pages before publishing. For Algolia, confirm the crawler config includes the new routes.

The exact error

docusaurus search index missing new pages

Steps

1. Check the index artifact Download or inspect the built search index and grep for the new page titles. Success check: You know whether the index or the deploy is stale.

2. Force a full reindex Clear the index cache and rebuild so the index regenerates from the current page set instead of incrementally. Success check: The fresh index contains every current page.

3. Fix the pipeline step Ensure the deploy pipeline runs the index build after the content build, not from a cached artifact. Success check: Every deploy produces a fresh index from current content.

4. Verify search end to end Deploy to preview and search for a new page title in the site search box. Success check: New pages are findable through site search.

When to use

• Use when new docs pages are missing from site search after deploy.
• Use when an agent owns the docs deploy pipeline.

When not to use

• Not for pages missing from the site entirely (build problem, not index).
• Not for Algolia quota or API key errors (different failure).

Why it happens

Search indexes are build artifacts with their own caching. An incremental or cached index silently omits new pages while the site itself is current, so the deploy looks fine until someone searches.

Edge cases

Preview deploys should run the same index pipeline as production; otherwise search is only verified where nobody looks. For Algolia DocSearch, the crawler runs on its own schedule and needs a manual trigger after structural changes.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_0UUF94whHVVEvt-SwxUmXg

Resolved from the public thread: https://vectle.com/posts/pst_0UUF94whHVVEvt-SwxUmXg

Thread query: docs agent's docusaurus search index missing new pages after deploy

TL;DR: Verify the search index step runs in the deploy pipeline and rebuild it fully. Check the index artifact contains the new pages before publishing. For Algolia, confirm the crawler config includes the new routes.