{"record":{"id":"648acc1807530722","repo":"vitest-dev/vitest","slug":"environment-ctx-environment-name-is-not-a-val","errorCode":null,"errorMessage":"Environment \"${ctx.environment.name}\" is not a valid environment. Path \"${packageId}\" doesn't support vm environment because it doesn't provide \"setupVM\" method.","messagePattern":"Environment \"(.+?)\" is not a valid environment\\. Path \"(.+?)\" doesn't support vm environment because it doesn't provide \"setupVM\" method\\.","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"packages/vitest/src/runtime/workers/vm.ts","lineNumber":54,"sourceCode":"  const { environment } = await loadEnvironment(ctx.environment.name, ctx.config.root, rpc, traces, true)\n  state.environment = environment\n\n  // let the server transform this file's import graph while this worker is\n  // busy importing the environment package (jsdom takes ~0.5s per worker) —\n  // the server is otherwise idle during that window on a cold start. The\n  // transforms also land in the `fetchWarmModules` snapshot, so the worker's\n  // own fetches short-circuit to disk reads. Failures are ignored: the\n  // worker's own fetch reports them with the proper import context.\n  rpc.prewarmModuleGraph(\n    environment.viteEnvironment || environment.name,\n    ctx.files.map(file => file.filepath),\n  ).catch(() => {})\n\n  if (!environment.setupVM) {\n    const envName = ctx.environment.name\n    const packageId\n      = envName[0] === '.' ? envName : `vitest-environment-${envName}`\n    throw new TypeError(\n      `Environment \"${ctx.environment.name}\" is not a valid environment. `\n      + `Path \"${packageId}\" doesn't support vm environment because it doesn't provide \"setupVM\" method.`,\n    )\n  }\n\n  const vm = await traces.$(\n    'vitest.runtime.environment.setup',\n    {\n      attributes: {\n        'vitest.environment': environment.name,\n        'vitest.environment.vite_environment': environment.viteEnvironment || environment.name,\n      },\n    },\n    () => environment.setupVM!(ctx.environment.options || ctx.config.environmentOptions || {}),\n  )\n\n  state.durations.environment = performance.now() - beforeEnvironmentTime\n","sourceCodeStart":36,"sourceCodeEnd":72,"githubUrl":"https://github.com/vitest-dev/vitest/blob/1fa9837ec26533512fdcad8baebf249771bd340a/packages/vitest/src/runtime/workers/vm.ts#L36-L72","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use a non-vm pool (threads or forks) with that environment: test.pool='threads'.","Upgrade or switch to an environment version that implements setupVM (check the package exports for setupVM).","If it is your own environment, add an exported setupVM(options) returning an object with getVmContext().","Confirm the environment name resolves to the intended package and is installed (not a typo)."],"exampleFix":"// before\nexport default defineConfig({ test: { environment: 'jsdom', pool: 'vmThreads' } })\n\n// after\nexport default defineConfig({ test: { environment: 'jsdom', pool: 'threads' } })","handlingStrategy":"type-guard","validationCode":"import env from 'vitest-environment-x'\nif (typeof env.setupVM !== 'function' && config.pool.startsWith('vm')) {\n  throw new Error('this environment does not support the vm pool')\n}","typeGuard":"function supportsVm(env) {\n  return typeof env?.setupVM === 'function'\n}","tryCatchPattern":null,"preventionTips":["Check an environment exports setupVM before pairing it with a vm pool.","Use threads/forks for environments without VM support.","Upgrade environment packages to versions with VM support."],"tags":["environment","vm","pool","setupvm"],"backgroundTag":null,"analyzedSha":"1fa9837ec26533512fdcad8baebf249771bd340a","analyzedAt":"2026-08-11T16:11:39.638Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}