docusaurus Error: No docs version found after version bump

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: 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

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.