vitest-dev/vitest · error · TypeError

Environment "${ctx.environment.name}" is not a valid environ

Error message

Environment "${ctx.environment.name}" is not a valid environment. Path "${packageId}" doesn't support vm environment because it doesn't provide "setupVM" method.

What it means

In the VM pool (runVmTests, vm.ts:48-56) Vitest requires the environment package to implement a setupVM method that returns a VM context, because the whole pool runs tests inside node:vm. If the resolved vitest-environment-<name> package only exports setup (not setupVM), this TypeError is thrown with the resolved packageId.

Source

Thrown at packages/vitest/src/runtime/workers/vm.ts:52

  const { environment } = await loadEnvironment(ctx.environment.name, ctx.config.root, rpc, traces, true)
  state.environment = environment

  // let the server transform this file's import graph while this worker is
  // busy importing the environment package (jsdom takes ~0.5s per worker) —
  // the server is otherwise idle during that window on a cold start. The
  // transforms also land in the `fetchWarmModules` snapshot, so the worker's
  // own fetches short-circuit to disk reads. Failures are ignored: the
  // worker's own fetch reports them with the proper import context.
  rpc.prewarmModuleGraph(
    environment.viteEnvironment || environment.name,
    ctx.files.map(file => file.filepath),
  ).catch(() => {})

  if (!environment.setupVM) {
    const envName = ctx.environment.name
    const packageId
      = envName[0] === '.' ? envName : `vitest-environment-${envName}`
    throw new TypeError(
      `Environment "${ctx.environment.name}" is not a valid environment. `
      + `Path "${packageId}" doesn't support vm environment because it doesn't provide "setupVM" method.`,
    )
  }

  const vm = await traces.$(
    'vitest.runtime.environment.setup',
    {
      attributes: {
        'vitest.environment': environment.name,
        'vitest.environment.vite_environment': environment.viteEnvironment || environment.name,
      },
    },
    () => environment.setupVM!(ctx.environment.options || ctx.config.environmentOptions || {}),
  )

  state.durations.environment = performance.now() - beforeEnvironmentTime

View on GitHub (pinned to d568f8ce37)

Solutions

Use pool: 'threads' or 'forks' if your environment only provides setup.
Add a setupVM(options) method to your custom environment that returns an object with getVmContext().
Upgrade the environment package (e.g. @vitest/browser or jsdom env) to a version that supports VM mode.

Example fix

// before: custom env with only setup
export default {
  name: 'myenv',
  setup(global, options) { /* ... */ },
}

// after: add setupVM for vm pool support
import vm from 'node:vm'
export default {
  name: 'myenv',
  setup(global, options) { /* ... */ },
  setupVM(options) {
    const context = vm.createContext({})
    return { getVmContext: () => context, teardown() { /* ... */ } }
  },
}

Defensive patterns

Strategy: type-guard

Validate before calling

import type { Environment } from 'vitest'

function supportsVm(env: Environment): boolean {
  return typeof (env as any).setupVM === 'function'
}

// before opting into vmThreads, check:
if (pool.startsWith('vm') && !supportsVm(resolvedEnvironment)) {
  throw new Error(`Environment '${resolvedEnvironment.name}' cannot be used with ${pool}; it lacks setupVM.`)
}

Type guard

type VmCapableEnvironment = Environment & { setupVM: (options: unknown) => { getVmContext: () => unknown } }

function isVmCapable(env: Environment): env is VmCapableEnvironment {
  return typeof (env as any).setupVM === 'function'
}

Prevention

Before switching to vmThreads/vmForks, confirm the environment package documents setupVM support.
When authoring a custom environment, implement both setup and setupVM from the start.
Pin environment package versions that match your vitest major.

When it happens

Trigger: Using pool: 'vmThreads' or 'vmForks' with an environment whose package lacks setupVM — e.g. a custom environment that only implements setup, or a built-in/environment combo that does not support the VM isolation model. Reached when environment.setupVM is falsy after loadEnvironment resolves.

Common situations: Switching from threads to vmThreads without verifying the environment supports VM mode; writing a custom environment and forgetting setupVM; using an older environment package version that predates setupVM support.

Related errors

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