## TL;DR
detect-secrets stamps the baseline with the scanner version, and a newer scanner refuses to trust an older baseline. Regenerate the baseline with the upgraded version (back up the old one first), re-approve any new hits, and pin the version in CI so it stops drifting. Scans go green again immediately.

## Error
```text
detect-secrets: baseline version mismatch after upgrade
```

## Steps
1. Confirm the mismatch: open `.secrets.baseline` and compare its `version` field with `detect-secrets --version`. Expected: the two versions differ, confirming the upgrade is the cause.
2. Back up the old baseline: copy `.secrets.baseline` to `.secrets.baseline.bak`. Expected: you can diff later to see exactly which findings changed.
3. Regenerate with the new scanner: run `detect-secrets scan --update .secrets.baseline` from the repo root. Expected: the version field updates and the command exits 0.
4. Review the diff between the backup and the new baseline, and audit any newly flagged secrets instead of blindly approving them. Expected: only expected new findings appear; real leaks get rotated.
5. Pin the scanner version in CI (for example in the pre-commit config or requirements file) so the next upgrade is deliberate. Expected: no surprise mismatches on unrelated pipeline runs.

## When to use
- `detect-secrets scan` or the pre-commit hook fails with a baseline version mismatch
- You just upgraded detect-secrets via pip or pre-commit autoupdate
- CI and local checkouts use different detect-secrets versions

## When not to use
- The baseline is corrupt JSON (different error, recreate from scratch)
- You want to add a custom plugin (plugin development, not versioning)

## Tool compatibility
- detect-secrets 1.4.x / 1.5.x (`scan --update`, `.secrets.baseline` format)

## Variant phrasings
### baseline generated with older version warning
Same fix: regenerate with the current scanner. The warning is informational, but the mismatch error is fatal, so regenerate before it blocks the hook.

### pre-commit detect-secrets fails after autoupdate
Pin `rev:` in the pre-commit config to the version that generated the baseline, or regenerate the baseline right after bumping the rev.

## Why it happens
Plugin output formats and default rule sets change between detect-secrets releases, so a baseline written by 1.4.x is not trustworthy input for 1.5.x. The version stamp forces an explicit regeneration so nobody silently scans against stale assumptions.

## Provenance

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