vitest-dev/vitest · error · TypeError

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

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

For the vm/vmThreads pool Vitest requires the resolved environment object to expose a setupVM(options) method. When environment.setupVM is falsy it throws a TypeError naming the environment and the inferred package id (vitest-environment-<name>, or the raw name if it starts with '.'). The message explains the package does not support the vm environment.

Solutions

1. Use a non-vm pool (threads or forks) with that environment: test.pool='threads'.
2. Upgrade or switch to an environment version that implements setupVM (check the package exports for setupVM).
3. If it is your own environment, add an exported setupVM(options) returning an object with getVmContext().
4. Confirm the environment name resolves to the intended package and is installed (not a typo).

Example fix

// before
export default defineConfig({ test: { environment: 'jsdom', pool: 'vmThreads' } })

// after
export default defineConfig({ test: { environment: 'jsdom', pool: 'threads' } })

import env from 'vitest-environment-x'
if (typeof env.setupVM !== 'function' && config.pool.startsWith('vm')) {
  throw new Error('this environment does not support the vm pool')
}

function supportsVm(env) {
  return typeof env?.setupVM === 'function'
}

When it happens

Trigger: Configuring test.environment to a package (e.g. 'happy-dom', 'jsdom', or a custom env) that only implements setup() and not setupVM(), then running with test.pool='vm' or 'vmThreads'. The worker checks environment.setupVM before invoking it.

Common situations: Using an environment that predates/omits VM support with the vm pool, or a custom environment package that forgot to export setupVM. jsdom and happy-dom versions vary in VM support.

Related errors

• Environment doesn't provide "getVmContext" method. It…
• Environment doesn't provide a valid context. It should be…
• Pool " " cannot run with "experimental.viteModuleRunner…
• The VM environment was not defined in the Vite config. This…
• Cannot find environment for

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

Appendix: source

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

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