vitest-dev/vitest · error · Error

Pool "${context.pool}" cannot run with "experimental.viteMod

Error message

Pool "${context.pool}" cannot run with "experimental.viteModuleRunner: false". Please, use "threads" or "forks" instead.

What it means

setupVmWorker (vm.ts:177-180) refuses to start a VM pool when config.experimental.viteModuleRunner is false. The VM pool fundamentally relies on Vite's module runner to import the test entry inside the VM context, so the combination is unsupported; the error tells the user to switch to 'threads' or 'forks'.

Source

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

    await run(
      method,
      ctx.files,
      ctx.config,
      moduleRunner,
      traces,
    )
  }
  finally {
    await traces.$(
      'vitest.runtime.environment.teardown',
      () => vm.teardown?.(),
    )
  }
}

export function setupVmWorker(context: WorkerSetupContext): void {
  if (context.config.experimental.viteModuleRunner === false) {
    throw new Error(`Pool "${context.pool}" cannot run with "experimental.viteModuleRunner: false". Please, use "threads" or "forks" instead.`)
  }
}

View on GitHub (pinned to d568f8ce37)

Solutions

Set pool to 'threads' or 'forks' when using experimental.viteModuleRunner: false.
Or remove experimental.viteModuleRunner: false to keep using a VM pool.

Example fix

// before: incompatible combination
export default defineConfig({
  test: {
    pool: 'vmThreads',
    experimental: { viteModuleRunner: false },
  },
})

// after: pick one
export default defineConfig({
  test: {
    pool: 'threads',
    experimental: { viteModuleRunner: false },
  },
})

Defensive patterns

Strategy: validation

Validate before calling

function assertPoolRunnerCompatibility(pool: string, viteModuleRunner: boolean | undefined) {
  const isVmPool = pool === 'vmThreads' || pool === 'vmForks'
  if (isVmPool && viteModuleRunner === false) {
    throw new Error(
      `Pool '${pool}' requires experimental.viteModuleRunner !== false. Use 'threads' or 'forks'.`
    )
  }
}

Prevention

Treat viteModuleRunner:false as compatible only with threads/forks pools.
Add a config validator in CI that rejects vm* pools combined with viteModuleRunner:false.
Document the experimental flag combinations in the project's config.

When it happens

Trigger: Configuring both pool: 'vmThreads' (or 'vmForks') and experimental.viteModuleRunner: false in the same project. The guard runs at worker setup before any test executes.

Common situations: Opting into the native module runner (viteModuleRunner: false) for performance/Node-native imports but forgetting to also change the pool away from vm*; copying config snippets that combine incompatible experimental flags.

Related errors

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