vitejs/vite · error · Error

Environment "${name}" is not defined in the config.

Error message

Environment "${name}" is not defined in the config.

What it means

The DevEnvironment constructor at packages/vite/src/node/server/environment.ts:120 looks up config.environments[name]; if that key is absent it throws. Every environment created via new DevEnvironment(name, ...) must have a matching entry resolved from the user's config.environments (client and ssr are seeded by default).

Source

Thrown at packages/vite/src/node/server/environment.ts:120

  /**
   * Hot channel for this environment. If not provided or disabled,
   * it will be a noop channel that does nothing.
   *
   * @example
   * environment.hot.send({ type: 'full-reload' })
   */
  hot: NormalizedHotChannel

  public bundledDev?: BundledDev

  constructor(
    name: string,
    config: ResolvedConfig,
    context: DevEnvironmentContext,
  ) {
    let options = config.environments[name]
    if (!options) {
      throw new Error(`Environment "${name}" is not defined in the config.`)
    }
    if (context.options) {
      options = mergeConfig(
        options,
        context.options,
      ) as ResolvedEnvironmentOptions
    }
    super(name, config, options)
    if (
      options.isBundled ||
      (name === 'client' && config.experimental.bundledDev)
    ) {
      context.disableDepsOptimizer = true
      this.bundledDev = new BundledDev(this)
    }

    this._pendingRequests = new Map()

View on GitHub (pinned to 89620f09af)

Solutions

1. Declare the environment in config.environments (e.g. environments: { myEnv: {} }) before constructing/using it.
2. Fix the typo so the name passed to DevEnvironment matches an existing key.
3. If you only need default client/ssr, use server.environments.client or server.environments.ssr instead of inventing a name.

Example fix

// before
const env = new DevEnvironment('rsc', config, ctx)
// config has no environments.rsc

// after
export default defineConfig({
  environments: { rsc: { /* options */ } },
})

function assertEnvironmentDeclared(name: string, environments: Record<string, unknown>) {
  if (!(name in environments)) {
    throw new Error(`Environment "${name}" must be declared in config.environments`)
  }
}

function isDeclaredEnvironment(name: string, environments: Record<string, unknown>): boolean {
  return Object.prototype.hasOwnProperty.call(environments, name)
}

When it happens

Trigger: Constructing a DevEnvironment with an arbitrary name that was not declared in config.environments; a plugin spawning an environment named 'worker' without declaring environments.worker; renaming an environment in only one place; accessing server.environments.foo that was never configured.

Common situations: Custom plugin creating environments dynamically; migrating to the environments API without declaring every environment used; typo in an environment name between config and consumer code.

Related errors

• Invalid environment name "${name}". Environment names must o
• No environment found
• Environment "${name}" is not defined in the config.
• HTTP server not available
• Required environments configuration were stripped out in the

AI-assisted analysis of vitejs/vite@89620f09af (2026-08-03). Data as JSON: /data/errors/ecaa92703d2d8ca3.json. Report an issue: GitHub.