vitest-dev/vitest · error · Error

The environment ${environmentName} was not defined in the Vi

Error message

The environment ${environmentName} was not defined in the Vite config.

What it means

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.

Source

Thrown at packages/vitest/src/node/pools/rpc.ts:50

const warmExternals = new WeakMap<DevEnvironment, Record<string, FetchResult>>()

export function createMethodsRPC(project: TestProject, methodsOptions: MethodsOptions = {}): RuntimeRPC {
  const vitest = project.vitest
  const cacheFs = methodsOptions.cacheFs ?? false
  project.vitest.state.metadata[project.name] ??= {
    externalized: {},
    duration: {},
    tmps: {},
  }
  if (project.config.dumpDir && !existsSync(project.config.dumpDir)) {
    mkdirSync(project.config.dumpDir, { recursive: true })
  }
  project.vitest.state.metadata[project.name].dumpDir = project.config.dumpDir

  function getEnvironment(environmentName: string): DevEnvironment {
    const environment = project.vite.environments[environmentName]
    if (!environment) {
      throw new Error(`The environment ${environmentName} was not defined in the Vite config.`)
    }
    return environment
  }

  async function fetchModule(
    url: string,
    importer: string | undefined,
    environment: DevEnvironment,
    options?: FetchFunctionOptions,
    otelCarrier?: OTELCarrier,
    // per-module durations are only recorded for direct worker fetches: the
    // graph prewarm fetches whole levels concurrently, so its per-module wall
    // times measure the queue position, not the module's own transform cost
    accountModuleDuration = true,
  ): Promise<FetchResult | FetchCachedFileSystemResult> {
    const state = project.vitest.state
    const start = performance.now()

View on GitHub (pinned to d568f8ce37)

Solutions

1. Verify the environment name used by the project (config.environment or the pool default) matches a Vite environment actually registered.
2. Ensure Vite >= the minimum version required by your Vitest (auto-registers vitest environments).
3. Disable custom Vite plugins that mutate environments to isolate the cause.
4. Check the project name in the error path to find which workspace project has the bad environment reference.

Example fix

// before: custom environment name not registered
export default defineConfig({
  test: { environment: 'myenv' }, // no matching Vite environment
})

// after: use a registered/builtin environment, or register it in Vite
export default defineConfig({
  test: { environment: 'node' },
  environments: { myenv: { ... } }, // register the custom one if needed
})

// Confirm the environment is registered on the Vite server before running
function environmentExists(project, name) {
  return Object.prototype.hasOwnProperty.call(project.vite.environments, name)
}
const envName = project.config.environment
if (!environmentExists(project, envName)) {
  throw new Error(`Environment '${envName}' is not registered in Vite. Available: ${Object.keys(project.vite.environments).join(', ')}`)
}

function isRegisteredEnvironment(project, name) {
  return name in project.vite.environments
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Access denied to "${path}". See Vite config documentation fo
• Environment "${name}" is not a valid environment. Path "${pa
• Environment "${name}" is not a valid environment. Path "${pa
• Looks like you set "test.environment" to "browser". To enabl
• The VM environment was not defined in the Vite config. This

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