**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`.

```text
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