{"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":"validation","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/d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09/packages/vitest/src/node/pools/rpc.ts#L32-L68","documentation":"Thrown by the getEnvironment helper in the worker RPC layer when a fetch request names a Vite environment that is not present in project.vite.environments. Each worker fetches modules through a named Vite environment (e.g. 'ssr', 'client', or a custom one); if the named environment was never registered on the Vite server, module fetch cannot proceed.","triggerScenarios":"createMethodsRPC's fetch() calls getEnvironment(environmentName) at packages/vitest/src/node/pools/rpc.ts:48-52, receiving an environmentName from the worker that has no key in project.vite.environments. Reachable when the worker's pool/environment config references an environment Vite did not create.","commonSituations":"A custom Vite environment not declared in environments config; a Vitest/Vite version mismatch where expected environments are not auto-registered; misconfigured environment name in a workspace project; SSR/client environment removed by a custom Vite plugin.","solutions":["Verify the environment name used by the project (config.environment or the pool default) matches a Vite environment actually registered.","Ensure Vite >= the minimum version required by your Vitest (auto-registers vitest environments).","Disable custom Vite plugins that mutate environments to isolate the cause.","Check the project name in the error path to find which workspace project has the bad environment reference."],"exampleFix":"// before: custom environment name not registered\nexport default defineConfig({\n  test: { environment: 'myenv' }, // no matching Vite environment\n})\n\n// after: use a registered/builtin environment, or register it in Vite\nexport default defineConfig({\n  test: { environment: 'node' },\n  environments: { myenv: { ... } }, // register the custom one if needed\n})","handlingStrategy":"validation","validationCode":"// Confirm the environment is registered on the Vite server before running\nfunction environmentExists(project, name) {\n  return Object.prototype.hasOwnProperty.call(project.vite.environments, name)\n}\nconst envName = project.config.environment\nif (!environmentExists(project, envName)) {\n  throw new Error(`Environment '${envName}' is not registered in Vite. Available: ${Object.keys(project.vite.environments).join(', ')}`)\n}","typeGuard":"function isRegisteredEnvironment(project, name) {\n  return name in project.vite.environments\n}","tryCatchPattern":null,"preventionTips":["Use builtin environment names (node, jsdom, happy-dom) or register custom ones in Vite.","Keep Vitest and Vite versions compatible so environments auto-register.","Avoid custom Vite plugins that delete/replace environments."],"tags":["rpc","environment","vite","config"],"analyzedSha":"d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09","analyzedAt":"2026-08-03T20:23:56.861Z","schemaVersion":2}