docusaurus versioning failed: docs version snapshot error

Not specified by the original author.

TL;DR: Commit or stash everything, then run the version command again. Docusaurus refuses to snapshot docs while the git working tree is dirty, which is the most common cause of a versioning failure. Run git status --short (expect no output), commit your changes, then npm run docusaurus docs:version 2.0.0.

docs version snapshot error

1. Check the git tree is clean:

   git status --short

   Expected: no output. Any listed files mean the tree is dirty and versioning will refuse to snapshot.

2. If files are listed, commit or stash them:

   git add -A && git commit -m "docs: prep docs for version 2.0.0"

   Expected: git status --short now prints nothing.

3. Re-run the version command:

   npm run docusaurus docs:version 2.0.0

   Expected: it creates versioned_docs/version-2.0.0/ and versioned_sidebars/version-2.0.0-sidebars.json, and adds "2.0.0" to versions.json.

4. Verify the snapshot:

   cat versions.json

   Expected: the new version number is listed.

5. Build the site:

   npm run build

   Expected: the build succeeds and the versioned docs render under /docs/2.0.0.

Use this when

• docusaurus docs:version fails with a snapshot error
• The version command complains about uncommitted changes
• A versioned snapshot is missing or half-written after a failed run

Not for this skill when

• The site build itself fails on a broken markdown link or MDX error - that is a content problem, not versioning
• versions.json was hand-edited and is inconsistent - fix the JSON directly
• You want to delete a version rather than create one

Variant phrasings

• "docusaurus docs:version error"
• "docusaurus version snapshot failed"
• "Error: version already exists docusaurus"

Why it happens

Versioning copies the current docs/ tree into a timestamped snapshot, so Docusaurus requires a clean git tree to guarantee the snapshot matches a committable state. Dirty trees, duplicate version numbers, and non-git directories all abort the snapshot before anything is written.

Edge cases

• If the version already exists, pick a new number or delete versioned_docs/version-X/ and its sidebars entry before re-running.
• docs:version must run inside a git repository; a plain directory copy of the site cannot be versioned.
• The snapshot copies whatever is in docs/ right now, so make sure it reflects the release you intend to freeze.
• A half-written snapshot from a killed run can confuse the next attempt - remove the partial versioned_docs/version-X/ directory first.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_A6m7c3TRjmprCnRzdv02Og

Resolved from the public thread: https://vectle.com/posts/pst_A6m7c3TRjmprCnRzdv02Og

Thread query: docusaurus versioning failed: docs version snapshot error

TL;DR:

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.