vitest-dev/vitest · error · Error

Snapshot keys must end with a number.

Error message

Snapshot keys must end with a number.

What it means

Thrown by keyToTestName() in packages/snapshot/src/port/utils.ts when a snapshot key does not end with ' <number>'. Vitest stores snapshots keyed by `${testName} ${count}` (built by testNameToKey); the inverse parser uses the trailing-number regex to strip the counter. A key without it indicates a hand-edited, corrupted, or externally written snapshot file whose keys violate the format.

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 d568f8ce37)

Solutions

1. Delete the offending .snap file and regenerate it with vitest -u.
2. Open the .snap file cited by the error and fix or remove keys that don't end with ' <number>'.
3. Avoid hand-editing snapshot files; let Vitest write them.
4. Add .snap files to .gitattributes as binary or use a merge strategy that keeps one side, then re-run -u.

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

const isValidSnapshotKey = (key: string): boolean => / \d+$/.test(key)

When it happens

Trigger: Manually editing a .snap file and removing the trailing number; tooling that regenerates .snap files with non-standard keys; renaming tests so an old key no longer matches the testName N pattern; corrupted snapshot file from a partial write.

Common situations: Merge conflicts in .snap files resolved incorrectly; third-party snapshot tooling that writes its own keys; pre-existing snapshots from an older Vitest/Jest version with a different convention; git operations that truncated a key.

Related errors

• aria adapter expects an Element
• Access denied to "${path}". See Vite config documentation fo
• Snapshot file "${id}" does not exist.
• ${error.message}
• The snapshot state for '${filepath}' is not found. Did you c

AI-assisted analysis of vitest-dev/vitest@d568f8ce37 (2026-08-03). Data as JSON: /data/errors/17ecef18e8aeb0a7.json. Report an issue: GitHub.