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 "setup" or/and "setupVM" method.

What it means

When loading a custom environment (`vitest-environment-<name>` or a path), Vitest imports the module and requires a default export that is an object exposing `setup` and/or `setupVM`. If the default export is missing, not an object, or lacks those methods, the loader rejects it as invalid so the environment contract is enforced up front rather than failing cryptically during test setup.

Source

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

export async function loadNativeEnvironment(
  name: string,
  root: string,
  traces: Traces,
): Promise<Environment> {
  const packageId = name[0] === '.' || name[0] === '/'
    ? pathToFileURL(resolve(root, name)).toString()
    : import.meta.resolve(`vitest-environment-${name}`, pathToFileURL(root).toString())
  const pkg = await traces.$(
    'vitest.runtime.environment.import',
    () => 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

View on GitHub (pinned to d568f8ce37)

Solutions

1. Ensure the environment module has `export default { name, setup(opts) { ... return { teardown() {} } } }` (and/or `setupVM`).
2. If using CommonJS, use `module.exports = { setup, setupVM }` so Vitest sees it as the default object.
3. Verify the resolved path actually points to your environment file (check the error's `packageId`).

Example fix

// before
export function setup() { return { teardown() {} } }
// after
export default {
  name: 'myenv',
  setup({ provide }) { return { teardown() {} } },
}

// validate your environment module before publishing
import * as env from './my-env.js'
const ok = typeof env.default === 'object' && env.default !== null
  && (typeof env.default.setup === 'function' || typeof env.default.setupVM === 'function')

import type { Environment } from 'vitest'
function isEnvironment(v: unknown): v is Environment {
  return typeof v === 'object' && v !== null
    && (typeof (v as any).setup === 'function' || typeof (v as any).setupVM === 'function')
}

When it happens

Trigger: Setting `environment: 'myenv'` (resolving to `vitest-environment-myenv`) or `environment: './env.js'` where the module exports no default, exports a function/class as default, or exports a default object without `setup`/`setupVM`.

Common situations: Authoring a custom environment and forgetting the default export; naming the methods incorrectly (e.g. `init` instead of `setup`); CJS module whose `module.exports = ...` is not shaped as a default object; pointing `environment` at a path that re-exports incorrectly.

Related errors

• Environment "${name}" is not a valid environment. Path "${pa
• Snapshot environment module must have a default export objec
• Looks like you set "test.environment" to "browser". To enabl
• The environment ${environmentName} was not defined in the Vi
• Environment "${ctx.environment.name}" is not a valid environ

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