vitest-dev/vitest · error · TypeError

Environment " " is not a valid environment. Path " " should…

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

After validating the default export is an object, resolveEnvironmentFromModule checks the optional transformMode field. If present, it must be exactly 'ssr' or 'web'. Any other string (or a mistyped value like 'client', 'browser', 'node') triggers this TypeError. Note: transformMode itself is deprecated in Vitest 4 in favor of viteEnvironment, but it is still validated when present.

Solutions

  1. Set transformMode to 'ssr' or 'web', or remove it and use viteEnvironment ('ssr' or 'client') instead.
  2. If you wrote 'client', change it to 'web' (transformMode) or migrate to viteEnvironment: 'client'.
  3. Upgrade the environment package to the Vitest 4+ API using viteEnvironment.

Example fix

// before — invalid transformMode:
export default { name: 'myenv', transformMode: 'client', setup() {} }

// after — use viteEnvironment (Vitest 4+):
export default { name: 'myenv', viteEnvironment: 'client', setup() {} }
Defensive patterns

Strategy: validation

Validate before calling

const VALID_TRANSFORM_MODES = ['ssr', 'web'] as const
if (env.transformMode != null && !VALID_TRANSFORM_MODES.includes(env.transformMode)) {
  // fix the value or migrate to viteEnvironment
}

Type guard

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

Prevention

When it happens

Trigger: A custom environment sets `transformMode` to an invalid value such as 'client' (the old valid alias was only 'ssr'/'web'; 'client' maps from viteEnvironment, not transformMode), 'browser', 'node', or a typo.

Common situations: Migrating an environment from an older Vitest where transformMode accepted different values; setting transformMode to 'client' instead of 'web'; typo in the value.

Related errors

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

Appendix: 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 1fa9837ec2)