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

What it means

When a custom environment name (not one of the built-ins like 'node', 'jsdom', 'happy-dom') is configured, Vitest resolves the package `vitest-environment-${name}` and imports its default export. resolveEnvironmentFromModule checks that the default export exists and is an object. If the package has no default export, or the default is not an object, this TypeError fires, telling you the expected shape (an object with setup/setupVM methods).

Solutions

1. Ensure your environment package has `export default { name, setup() { ... } }` (or setupVM).
2. Verify the package name matches `vitest-environment-${name}` and is installed/resolvable.
3. Check that the resolved module's default export is a plain object, not a function or class.

Example fix

// before — environment package only has named export:
export function setup() { /* ... */ }

// after — default export object:
export default { name: 'myenv', setup() { /* ... */ } }

// before publishing a custom environment, verify:
const env = (await import('vitest-environment-myenv')).default
if (!(env && typeof env === 'object' && typeof env.setup === 'function')) {
  throw new Error('environment package must default-export { name, setup } ')
}

function isValidEnvironment(v: unknown): v is { name: string; setup: Function } {
  return typeof v === 'object' && v !== null
    && typeof (v as any).setup === 'function'
}

When it happens

Trigger: Setting `environment: 'myenv'` in config where the package `vitest-environment-myenv` either doesn't exist, doesn't have a default export, or exports a non-object default (e.g. a function or string).

Common situations: Writing a custom Vitest environment but forgetting `export default`; naming mismatch between config and package; package misconfigured with named export instead of default; broken/partial environment package.

Related errors

• Environment " " is not a valid environment. Path " " should…
• The environment was not defined in the Vite config.
• vitest/browser can be imported only inside the Browser…
• Access denied to " ". See Vite config documentation for…
• All browser instances within a project must use the same…

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

Appendix: source

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

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