vitest-dev/vitest · error · Error

Raw snapshot is required

Error message

Raw snapshot is required

What it means

Thrown by SnapshotClient.assertRaw() when options.rawSnapshot is undefined. Raw snapshots (toMatchSnapshot with a { raw: true } option or toMatchRawSnapshot) require a RawSnapshotInfo object so Vitest knows which file to write the unformatted bytes/string to. Calling assertRaw without it is a programmer error — there is no raw target to write to.

Source

Thrown at packages/snapshot/src/client.ts:348

      received: stableResult.rendered,
      expectedSnapshot,
      matchResult,
      isInline,
      error,
      assertionName: options.assertionName,
    })

    return {
      pass,
      message: () => `Snapshot \`${key}\` mismatched`,
      actual: actual?.trim(),
      expected: expected?.trim(),
    }
  }

  async assertRaw(options: AssertOptions): Promise<void> {
    if (!options.rawSnapshot) {
      throw new Error('Raw snapshot is required')
    }

    const { filepath, rawSnapshot } = options

    if (rawSnapshot.content == null) {
      if (!filepath) {
        throw new Error('Snapshot cannot be used outside of test')
      }

      const snapshotState = this.getSnapshotState(filepath)

      // save the filepath, so it don't lose even if the await make it out-of-context
      options.filepath ||= filepath
      // resolve and read the raw snapshot file
      rawSnapshot.file = await snapshotState.environment.resolveRawPath(
        filepath,
        rawSnapshot.file,
      )

View on GitHub (pinned to d568f8ce37)

Solutions

1. Pass options.rawSnapshot = { file: '<path>', content: undefined } (or let Vitest fill content) when calling assertRaw.
2. Use expect(value).toMatchRawSnapshot() directly instead of a custom wrapper so Vitest builds the RawSnapshotInfo for you.
3. If you only need a normal snapshot, call client.assert(options) instead of client.assertRaw(options).
4. Audit custom matchers to ensure they forward the rawSnapshot option through.

Example fix

// before
await client.assertRaw({ filepath, received })

// after
await client.assertRaw({ filepath, received, rawSnapshot: { file: filepath + '.raw' } })

function isRawSnapshotInfo(v: unknown): v is { file: string; content?: string } {
  return typeof v === 'object' && v !== null && typeof (v as any).file === 'string'
}
if (!isRawSnapshotInfo(options.rawSnapshot)) {
  throw new TypeError('rawSnapshot must be { file: string, content?: string }')
}

const isRawSnapshotInfo = (v: unknown): v is { file: string; content?: string } =>
  typeof v === 'object' && v !== null && typeof (v as any).file === 'string'

When it happens

Trigger: Calling client.assertRaw({...}) without a rawSnapshot field; using a custom matcher that routes to assertRaw but forgets to build the RawSnapshotInfo; calling expect(value).toMatchRawSnapshot() through a shim that drops the raw option.

Common situations: Writing a custom expect.extend matcher around raw snapshots; migrating from toMatchSnapshot to toMatchRawSnapshot and forgetting the raw marker; third-party plugins that wrap the snapshot client incorrectly.

Related errors

• aria adapter expects an Element
• input with type=checkbox or type=radio cannot be used with .
• 'toMatchScreenshot' cannot be used with "not"
• Locator.filter expects at least one filter. None provided.
• Access denied to "${path}". See Vite config documentation fo

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