vitest-dev/vitest · error · Error

Snapshot keys must end with a number.

Error message

Snapshot keys must end with a number.

What it means

Vitest stores each snapshot under a key formed as `${testName} ${count}` (a space followed by one or more digits). keyToTestName reverses that format and asserts the key matches `/ \d+$/`. If a snapshot key in a .snap file is missing its trailing numeric suffix, the parse aborts with this error. It almost always means the snapshot file was hand-edited or corrupted.

Solutions

1. Delete the offending .snap file and re-run tests so Vitest regenerates every key with the correct ` name N` suffix.
2. Inspect the .snap file and fix the malformed key by appending ` 1` (space + count) to match the `testName N` format.
3. Check git history of the .snap file to find what rewrote the key and prevent that tool/process from modifying snapshots.

Example fix

// before — .snap file contains:
// exports[`my test`] = `"value"`;

// after — append the numeric suffix:
// exports[`my test 1`] = `"value"`;

function isValidSnapshotKey(key: string): boolean {
  return / \d+$/.test(key)
}

// before reading a .snap file's keys:
if (!isValidSnapshotKey(key)) {
  // regenerate the snapshot instead of parsing
}

function isWellFormedSnapshotKey(key: string): boolean {
  return typeof key === 'string' && / \d+$/.test(key)
}

When it happens

Trigger: Calling toMatchSnapshot/toMatchInlineSnapshot against a .snap file whose key was manually edited to remove the trailing number, or a .snap file generated by an incompatible/older snapshot format. Also triggered if a custom snapshot serializer or external tool rewrites keys without the count suffix.

Common situations: Manually editing .snap files to rename tests; merging snapshot files across branches where keys got mangled; running tests after a Vitest major version upgrade that changed key formatting.

Related errors

• aria adapter expects an Element
• Assertion name is not set. This is a bug in Vitest. Please…
• cannot read when saving inline snapshot
• expect.poll() is not supported in combination with .
• expected must be a function, received

AI-assisted analysis of vitest-dev/vitest@1fa9837ec2 (2026-08-11). Data as JSON: /api/errors/17ecef18e8aeb0a7. Report an issue: GitHub.

Appendix: source

Thrown at packages/snapshot/src/port/utils.ts:24

 */

import type { OptionsReceived as PrettyFormatOptions } from '@vitest/pretty-format'
import type { SnapshotData, SnapshotStateOptions } from '../types'
import type { SnapshotEnvironment } from '../types/environment'
import { format as prettyFormat } from '@vitest/pretty-format'
import { isObject } from '@vitest/utils/helpers'
import naturalCompare from 'natural-compare'
import { getSerializers } from './plugins'

// TODO: rewrite and clean up

export function testNameToKey(testName: string, count: number): string {
  return `${testName} ${count}`
}

export function keyToTestName(key: string): string {
  if (!/ \d+$/.test(key)) {
    throw new Error('Snapshot keys must end with a number.')
  }

  return key.replace(/ \d+$/, '')
}

export function getSnapshotData(
  content: string | null,
  options: SnapshotStateOptions,
): {
  data: SnapshotData
  dirty: boolean
} {
  const update = options.updateSnapshot
  const data = Object.create(null)
  let snapshotContents = ''
  let dirty = false

  if (content != null) {

View on GitHub (pinned to 1fa9837ec2)