avajs/ava · error · VersionMismatchError

Unexpected snapshot version

Error message

Unexpected snapshot version

What it means

AVA stamps each snapshot file with a format version number, read as a UInt16 after the header newline. When that stored version differs from the VERSION the running AVA supports, it throws VersionMismatchError, because the binary layout (hash/compressed offsets) cannot be trusted across versions.

Source

Thrown at lib/snapshot-manager.js:242

	], READABLE_PREFIX.byteLength + VERSION_HEADER.byteLength + SHA_256_HASH_LENGTH + compressed.byteLength);
}

export function extractCompressedSnapshot(buffer, snapPath) {
	if (isLegacySnapshot(buffer)) {
		throw new LegacyError(snapPath);
	}

	// The version starts after the readable prefix, which is ended by a newline
	// byte (0x0A).
	const newline = buffer.indexOf(0x0A);
	if (newline === -1) {
		throw new InvalidSnapshotError(snapPath);
	}

	const versionOffset = newline + 1;
	const version = buffer.readUInt16LE(versionOffset);
	if (version !== VERSION) {
		throw new VersionMismatchError(snapPath, version);
	}

	const sha256sumOffset = versionOffset + 2;
	const compressedOffset = sha256sumOffset + SHA_256_HASH_LENGTH;
	const compressed = buffer.slice(compressedOffset);

	return {
		version, compressed, sha256sumOffset, compressedOffset,
	};
}

function decodeSnapshots(buffer, snapPath) {
	const {compressed, sha256sumOffset, compressedOffset} = extractCompressedSnapshot(buffer, snapPath);

	const sha256sum = crypto.createHash('sha256').update(compressed).digest();
	const expectedSum = buffer.slice(sha256sumOffset, compressedOffset);
	if (!sha256sum.equals(expectedSum)) {
		throw new ChecksumError(snapPath);

View on GitHub (pinned to bbfd946322)

Solutions

1. Align AVA versions: update (or pin via lockfile) so the version that reads the snapshots matches the one that wrote them, then run --update-snapshots if needed
2. Delete stale .snap files and regenerate with npx ava --update-snapshots
3. Commit regenerated snapshots so all environments share the current version

Example fix

// before
npm install
// after
npm install && npx ava --update-snapshots && git add test/snapshots

const buf = fs.readFileSync(snapPath);
const nl = buf.indexOf(0x0A);
if (nl !== -1) {
  const version = buf.readUInt16LE(nl + 1);
  if (version !== CURRENT_VERSION) console.warn(`snapshot version ${version} != ${CURRENT_VERSION}; run --update-snapshots`);
}

function hasCompatibleVersion(buffer, expected) {
  const nl = buffer.indexOf(0x0A);
  return nl !== -1 && buffer.readUInt16LE(nl + 1) === expected;
}

try {
  decodeSnapshots(buffer, snapPath);
} catch (err) {
  if (/Unexpected snapshot version/i.test(err.message)) {
    // align AVA versions across environments, then npx ava --update-snapshots
  } else { throw err; }
}

When it happens

Trigger: Reading a .snap file written by a newer or older AVA whose VERSION constant differs; mixing AVA versions (e.g. different versions in local node_modules vs CI lockfile) on the same snapshot files.

Common situations: Dowgrading AVA after snapshots were written by a newer release; parallel branches on different AVA versions sharing one snapshot directory; failing to update the lockfile in CI.

Related errors

• Legacy snapshot file
• Invalid snapshot file
• Checksum mismatch
• Cannot record snapshot ${index} for ${JSON.stringify(belongs

AI-assisted analysis of avajs/ava@bbfd946322 (2026-09-02). Data as JSON: /api/errors/2c4fdec6c02990fd. Report an issue: GitHub.