vitest-dev/vitest · error · Error

Snapshot environment module must have a default export objec

Error message

Snapshot environment module must have a default export object with a shape of `SnapshotEnvironment`

What it means

When `snapshotEnvironment` is configured, Vitest imports that module via the test module runner and expects a default export that is an object conforming to the `SnapshotEnvironment` interface (methods like `readSnapshotFile`, `writeSnapshotFile`, `resolveRawPath`, etc.). If `mod.default` is not an object, the resolver throws because the snapshot subsystem cannot operate without a valid environment implementation.

Source

Thrown at packages/vitest/src/integrations/snapshot/environments/resolveSnapshotEnvironment.ts:16

import type { SnapshotEnvironment } from '@vitest/snapshot/environment'
import type { SerializedConfig } from '../../../runtime/config'
import type { TestModuleRunner } from '../../../runtime/moduleRunner/testModuleRunner'

export async function resolveSnapshotEnvironment(
  config: SerializedConfig,
  moduleRunner: TestModuleRunner,
): Promise<SnapshotEnvironment> {
  if (!config.snapshotEnvironment) {
    const { VitestNodeSnapshotEnvironment } = await import('./node')
    return new VitestNodeSnapshotEnvironment()
  }

  const mod = await moduleRunner.import(config.snapshotEnvironment)
  if (typeof mod.default !== 'object' || !mod.default) {
    throw new Error(
      'Snapshot environment module must have a default export object with a shape of `SnapshotEnvironment`',
    )
  }
  return mod.default
}

View on GitHub (pinned to d568f8ce37)

Solutions

1. Ensure the module has `export default { readSnapshotFile, writeSnapshotFile, resolveRawPath, removeSnapshotFile, resolveTestFilePath, ... }`.
2. If your environment is a class instance, export `new MyEnv()` as the default.
3. Verify the path in `snapshotEnvironment` resolves to the intended file.

Example fix

// before
export class MySnapshotEnv { readSnapshotFile() {} /* ... */ }
// after
class MySnapshotEnv { readSnapshotFile() {} /* ... */ }
export default new MySnapshotEnv()

import * as mod from './my-snapshot-env.js'
if (typeof mod.default !== 'object' || !mod.default) {
  throw new Error('snapshot env must default-export an object implementing SnapshotEnvironment')
}

import type { SnapshotEnvironment } from 'vitest/snapshot'
function isSnapshotEnv(v: unknown): v is SnapshotEnvironment {
  return typeof v === 'object' && v !== null
    && typeof (v as any).readSnapshotFile === 'function'
    && typeof (v as any).writeSnapshotFile === 'function'
}

When it happens

Trigger: Setting `test.snapshotEnvironment: './my-snapshot-env.js'` where the module has no default export, exports a class/function as default, or exports the environment as a named export instead of default.

Common situations: Authoring a custom snapshot environment (e.g. for an in-memory or remote store) and forgetting the `default` export, or migrating a named-export module to the expected default-object shape.

Related errors

• Environment "${name}" is not a valid environment. Path "${pa
• Environment "${name}" is not a valid environment. Path "${pa
• "snapshotFormat.compareKeys" function is not supported.
• invalid snapshot serializer file ${file}. Must export a defa
• invalid snapshot serializer in ${file}. Must have a 'test' m

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