avajs/ava · error · LegacyError

Legacy snapshot file

Error message

Legacy snapshot file

What it means

AVA throws this legacy-snapshot error when a snapshot file on disk was written by an old AVA version whose format predates the current compressed layout. Legacy files cannot be read by the current reader, and AVA refuses to guess at their contents, so extractCompressedSnapshot() short-circuits with a LegacyError as soon as isLegacySnapshot(buffer) is true.

Source

Thrown at lib/snapshot-manager.js:229

		ignoreGlobalTags: true,
		rejectUndefined: true,
		sortKeys: sortLengthFirstDeterministic,
		types,
	});
	const compressed = zlib.gzipSync(encoded);
	compressed[9] = 0x03; // Override the GZip header containing the OS to always be Linux
	const sha256sum = crypto.createHash('sha256').update(compressed).digest();
	return Buffer.concat([
		READABLE_PREFIX,
		VERSION_HEADER,
		sha256sum,
		compressed,
	], 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);

View on GitHub (pinned to bbfd946322)

Solutions

1. Delete the outdated .snap file and its .snap.new counterpart, then run AVA with the --update-snapshots flag to regenerate them in the current format
2. Downgrade AVA to the version that originally created the snapshot files if regeneration is not acceptable
3. Run npx ava --update-snapshots after the upgrade so all legacy files are rewritten

Example fix

// before (package.json)
"test": "ava"
// after
"test": "ava --update-snapshots" // or: delete *.snap then run once to recreate

const fs = require('fs');
const buf = fs.readFileSync(snapPath);
if (buf.slice(0, buf.indexOf(0x0A)).toString().includes('ava v4 snapshot')) {
  console.warn(`${snapPath} uses the legacy format — regenerate with ava --update-snapshots`);
}

function isCurrentFormatSnapshot(buffer) {
  const newline = buffer.indexOf(0x0A);
  return newline !== -1 && !isLegacySnapshot(buffer);
}

try {
  decodeSnapshots(buffer, snapPath);
} catch (err) {
  if (/Legacy snapshot file/i.test(err.message)) {
    // regenerate: fs.rmSync(snapPath); run ava with --update-snapshots
  } else { throw err; }
}

When it happens

Trigger: Loading a .snap file created by an older AVA (pre-compression format) while running a current AVA version; checkout of a repo whose committed snapshots were generated years ago and never regenerated.

Common situations: Upgrading AVA in a project with long-lived snapshot files; CI picking up a newer AVA than the one that generated committed snapshots; rebasing onto a branch where the snapshot format changed.

Related errors

• Invalid snapshot file
• Unexpected snapshot version
• 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/53daefc2267ffb67. Report an issue: GitHub.