docusaurus versioning failed: docs version snapshot error

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.

1. 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.

1. 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.

1. Verify the snapshot:

   cat versions.json

Expected: the new version number is listed.

1. 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