{"record":{"id":"53daefc2267ffb67","repo":"avajs/ava","slug":"legacy-snapshot-file","errorCode":null,"errorMessage":"Legacy snapshot file","messagePattern":"Legacy snapshot file","errorType":"exception","errorClass":"LegacyError","httpStatus":null,"severity":"error","filePath":"lib/snapshot-manager.js","lineNumber":229,"sourceCode":"\t\tignoreGlobalTags: true,\n\t\trejectUndefined: true,\n\t\tsortKeys: sortLengthFirstDeterministic,\n\t\ttypes,\n\t});\n\tconst compressed = zlib.gzipSync(encoded);\n\tcompressed[9] = 0x03; // Override the GZip header containing the OS to always be Linux\n\tconst sha256sum = crypto.createHash('sha256').update(compressed).digest();\n\treturn Buffer.concat([\n\t\tREADABLE_PREFIX,\n\t\tVERSION_HEADER,\n\t\tsha256sum,\n\t\tcompressed,\n\t], READABLE_PREFIX.byteLength + VERSION_HEADER.byteLength + SHA_256_HASH_LENGTH + compressed.byteLength);\n}\n\nexport function extractCompressedSnapshot(buffer, snapPath) {\n\tif (isLegacySnapshot(buffer)) {\n\t\tthrow new LegacyError(snapPath);\n\t}\n\n\t// The version starts after the readable prefix, which is ended by a newline\n\t// byte (0x0A).\n\tconst newline = buffer.indexOf(0x0A);\n\tif (newline === -1) {\n\t\tthrow new InvalidSnapshotError(snapPath);\n\t}\n\n\tconst versionOffset = newline + 1;\n\tconst version = buffer.readUInt16LE(versionOffset);\n\tif (version !== VERSION) {\n\t\tthrow new VersionMismatchError(snapPath, version);\n\t}\n\n\tconst sha256sumOffset = versionOffset + 2;\n\tconst compressedOffset = sha256sumOffset + SHA_256_HASH_LENGTH;\n\tconst compressed = buffer.slice(compressedOffset);","sourceCodeStart":211,"sourceCodeEnd":247,"githubUrl":"https://github.com/avajs/ava/blob/bbfd946322fdeca2b547a691d947fb4e18c0c67f/lib/snapshot-manager.js#L211-L247","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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","Downgrade AVA to the version that originally created the snapshot files if regeneration is not acceptable","Run npx ava --update-snapshots after the upgrade so all legacy files are rewritten"],"exampleFix":"// before (package.json)\n\"test\": \"ava\"\n// after\n\"test\": \"ava --update-snapshots\" // or: delete *.snap then run once to recreate","handlingStrategy":"fallback","validationCode":"const fs = require('fs');\nconst buf = fs.readFileSync(snapPath);\nif (buf.slice(0, buf.indexOf(0x0A)).toString().includes('ava v4 snapshot')) {\n  console.warn(`${snapPath} uses the legacy format — regenerate with ava --update-snapshots`);\n}","typeGuard":"function isCurrentFormatSnapshot(buffer) {\n  const newline = buffer.indexOf(0x0A);\n  return newline !== -1 && !isLegacySnapshot(buffer);\n}","tryCatchPattern":"try {\n  decodeSnapshots(buffer, snapPath);\n} catch (err) {\n  if (/Legacy snapshot file/i.test(err.message)) {\n    // regenerate: fs.rmSync(snapPath); run ava with --update-snapshots\n  } else { throw err; }\n}","preventionTips":["Pin the AVA version in package.json and commit the lockfile","After upgrading AVA, always run --update-snapshots once and commit regenerated files","Audit committed .snap files when migrating a legacy repo"],"tags":["snapshots","versioning","backward-compatibility"],"backgroundTag":"legacy-snapshot-format","analyzedSha":"bbfd946322fdeca2b547a691d947fb4e18c0c67f","analyzedAt":"2026-09-02T01:24:43.834Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T06:17:21.866Z"}