vitest-dev/vitest · error · TypeError

Environment "${name}" is not a valid environment. Path "${pa

Error message

Environment "${name}" is not a valid environment. Path "${packageId}" should export default object with a "transformMode" method equal to "ssr" or "web", received "${environment.transformMode}".

What it means

A custom environment may optionally declare `transformMode` to control module transform, but it must be exactly `'ssr'` or `'web'`. Any other string value is rejected at load time to prevent ambiguous transform behavior. (Note: `transformMode` is deprecated in favor of `viteEnvironment` and emits a warning when present.)

Source

Thrown at packages/vitest/src/integrations/env/loader.ts:85

    () => import(packageId) as Promise<{ default: Environment }>,
  )
  return resolveEnvironmentFromModule(name, packageId, pkg)
}

function resolveEnvironmentFromModule(name: string, packageId: string, pkg: { default: Environment }) {
  if (!pkg || !pkg.default || typeof pkg.default !== 'object') {
    throw new TypeError(
      `Environment "${name}" is not a valid environment. `
      + `Path "${packageId}" should export default object with a "setup" or/and "setupVM" method.`,
    )
  }
  const environment = pkg.default
  if (
    environment.transformMode != null
    && environment.transformMode !== 'web'
    && environment.transformMode !== 'ssr'
  ) {
    throw new TypeError(
      `Environment "${name}" is not a valid environment. `
      + `Path "${packageId}" should export default object with a "transformMode" method equal to "ssr" or "web", received "${environment.transformMode}".`,
    )
  }
  if (environment.transformMode) {
    console.warn(`The Vitest environment ${environment.name} defines the "transformMode". This options was deprecated in Vitest 4 and will be removed in the next major version. Please, use "viteEnvironment" instead.`)
    // keep for backwards compat
    environment.viteEnvironment ??= environment.transformMode === 'ssr'
      ? 'ssr'
      : 'client'
  }
  return environment
}

export async function loadEnvironment(
  name: string,
  root: string,
  rpc: WorkerRPC,

View on GitHub (pinned to d568f8ce37)

Solutions

1. Set `transformMode` to either `'ssr'` or `'web'` (or omit it entirely).
2. Prefer the non-deprecated `viteEnvironment: 'ssr' | 'client'` over `transformMode`.
3. If you wrote `'client'`, change it to `'web'`; if you wrote `'node'`, change it to `'ssr'`.

Example fix

// before
export default { name: 'myenv', transformMode: 'browser', setup() {} }
// after
export default { name: 'myenv', viteEnvironment: 'client', setup() {} }

const mode = env.default.transformMode
if (mode != null && mode !== 'ssr' && mode !== 'web') {
  throw new Error(`invalid transformMode: ${mode}`)
}

function isValidTransformMode(v: unknown): v is 'ssr' | 'web' | undefined {
  return v == null || v === 'ssr' || v === 'web'
}

When it happens

Trigger: A custom environment whose default export sets `transformMode` to a value other than `'ssr'` or `'web'` — e.g. `'node'`, `'browser'`, `'client'`, `null`, a number, or a typo.

Common situations: Porting a config from another framework that uses different transform-mode vocabulary (e.g. `'browser'`), typos, or assuming `'client'` is valid (the legacy mapping converts `'web'`→`'client'` internally but the input must be `'web'`).

Related errors

• Environment "${name}" is not a valid environment. Path "${pa
• Snapshot environment module must have a default export objec
• Tag "${tag.name}": priority must be a non-negative number.
• Looks like you set "test.environment" to "browser". To enabl
• Unknown value for "test.listTags": ${listTags}

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