{"record":{"id":"1c308c447ea40bf8","repo":"vitest-dev/vitest","slug":"the-environment-environmentname-was-not-defined","errorCode":null,"errorMessage":"The environment ${environmentName} was not defined in the Vite config.","messagePattern":"The environment (.+?) was not defined in the Vite config\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/vitest/src/node/pools/rpc.ts","lineNumber":50,"sourceCode":"const warmExternals = new WeakMap<DevEnvironment, Record<string, FetchResult>>()\n\nexport function createMethodsRPC(project: TestProject, methodsOptions: MethodsOptions = {}): RuntimeRPC {\n  const vitest = project.vitest\n  const cacheFs = methodsOptions.cacheFs ?? false\n  project.vitest.state.metadata[project.name] ??= {\n    externalized: {},\n    duration: {},\n    tmps: {},\n  }\n  if (project.config.dumpDir && !existsSync(project.config.dumpDir)) {\n    mkdirSync(project.config.dumpDir, { recursive: true })\n  }\n  project.vitest.state.metadata[project.name].dumpDir = project.config.dumpDir\n\n  function getEnvironment(environmentName: string): DevEnvironment {\n    const environment = project.vite.environments[environmentName]\n    if (!environment) {\n      throw new Error(`The environment ${environmentName} was not defined in the Vite config.`)\n    }\n    return environment\n  }\n\n  async function fetchModule(\n    url: string,\n    importer: string | undefined,\n    environment: DevEnvironment,\n    options?: FetchFunctionOptions,\n    otelCarrier?: OTELCarrier,\n    // per-module durations are only recorded for direct worker fetches: the\n    // graph prewarm fetches whole levels concurrently, so its per-module wall\n    // times measure the queue position, not the module's own transform cost\n    accountModuleDuration = true,\n  ): Promise<FetchResult | FetchCachedFileSystemResult> {\n    const state = project.vitest.state\n    const start = performance.now()\n","sourceCodeStart":32,"sourceCodeEnd":68,"githubUrl":"https://github.com/vitest-dev/vitest/blob/1fa9837ec26533512fdcad8baebf249771bd340a/packages/vitest/src/node/pools/rpc.ts#L32-L68","documentation":"Thrown by the internal getEnvironment() helper inside the RPC pool worker when a fetch request names a Vite DevEnvironment that does not exist in project.vite.environments. The worker cannot transform or fetch modules for an environment it has no server for, so it aborts. This almost always points to a mismatch between the environment name a test/request uses and the environments actually declared in the Vite/Vitest config.","triggerScenarios":"An RPC 'fetch' call is made with an environmentName that is not a key of project.vite.environments. Happens when a test project references an environment (e.g. 'jsdom', 'happy-dom', a custom environment) that was never registered, or when pool/workers were spawned from a config that differs from the one the server used.","commonSituations":"Declaring environments only under test environment options but not in vite.config environments, typos in the environment name, using a custom environment plugin that failed to load, mismatched config between the main process and forked workers, or upgrading Vite/Vitest where the environments API shape changed.","solutions":["Verify the environment name in your vitest config 'environments' matches what the tests request (e.g. environments: { jsdom: {} }).","Check that the environment plugin (e.g. @vitest/browser, jsdom environment) is installed and loaded without errors.","Look at the server/Vite logs for environment registration failures that happened before this throw.","If using a custom environment, confirm its name property and that defineEnvironment/resolveEnvironment registered it.","On version upgrades, re-read the migration notes for the Vite environments API."],"exampleFix":"// before\nexport default defineConfig({\n  test: { environment: 'jsdom' }\n})\n// after - register the environment in vite environments\nimport { jsdom } from 'vitest/environments'\nexport default defineConfig({\n  environments: { jsdom },\n  test: { environment: 'jsdom' }\n})","handlingStrategy":"validation","validationCode":"// Before relying on an environment, confirm it was registered.\nimport type { Vite } from 'vite'\nfunction assertEnvironment(vite: Vite, name: string) {\n  if (!vite.environments?.[name]) {\n  throw new Error(`Environment \"${name}\" is not registered. Available: ${Object.keys(vite.environments || {}).join(', ')}`)\n  }\n}\n// assertEnvironment(project.vite, environmentName)","typeGuard":"const hasEnvironment = (vite: { environments?: Record<string, unknown> }, name: string): boolean =>\n  Boolean(vite.environments && name in vite.environments)","tryCatchPattern":null,"preventionTips":["Keep environment names in a single shared constant and reference it from both config and tests.","Add a startup check that every project.environment has a matching vite environments entry.","Restart watch sessions after renaming/removing environments.","Pin Vitest and Vite versions together to avoid environments API drift."],"tags":["config","environment","vite","worker-pool"],"backgroundTag":null,"analyzedSha":"1fa9837ec26533512fdcad8baebf249771bd340a","analyzedAt":"2026-08-11T16:11:39.638Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}