What causes "Environment "${name}" is not defined in the config." in vitejs/vite?

Declare the environment under environments in vite.config (e.g. environments: { worker: { ... } }).

vitejs/vite · error · Error

Environment " " is not defined in the config.

Error message

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

What it means

A BuildEnvironment instance is constructed for a named environment (client, ssr, or a custom one). The constructor reads config.environments[name]; if that key is absent it throws. This means the environment was requested for a build but never declared in vite.config.environments (nor created by the default environment backfill).

Solutions

Declare the environment under environments in vite.config (e.g. environments: { worker: { ... } }).
Check the spelling of the environment name in CLI flags and build calls.
Ensure any plugin that strips environments in configResolved does not remove the one you are building.

Example fix

// before
// vite build --environment worker  but config has no environments.worker
// after
export default defineConfig({
  environments: { worker: { build: { rollupOptions: { input: 'src/worker.ts' } } } }
})

Defensive patterns

Strategy: validation

Validate before calling

function environmentExists(config, name) {
  return Boolean(config && config.environments && Object.prototype.hasOwnProperty.call(config.environments, name));
}

Type guard

function isKnownEnvironment(name, config) {
  return name in (config?.environments ?? {});
}

Prevention

Declare every environment you build under config.environments.
Keep environment names consistent across CLI flags, configs, and plugins.

When it happens

Trigger: Calling builder.build(environment) or programmatic APIs that request an environment name not present in resolvedConfig.environments. Also triggered by --mode or environment-specific build flags that reference an undeclared environment.

Common situations: Custom environment names declared in a plugin's config hook that runs only in serve; building with a stale config; renaming an environment key without updating references; environment-agnostic scripts that iterate names and hit a removed one.

Related errors

AI-assisted analysis of vitejs/vite@b4d66fee14 (2026-08-11). Data as JSON: /api/errors/8a5168decb9c4147. Report an issue: GitHub.

Appendix: source

Thrown at packages/vite/src/node/build.ts:1755

export const toOutputFilePathInCss: typeof toOutputFilePathWithoutRuntime =
  toOutputFilePathWithoutRuntime
export const toOutputFilePathInHtml: typeof toOutputFilePathWithoutRuntime =
  toOutputFilePathWithoutRuntime

export class BuildEnvironment extends BaseEnvironment {
  mode = 'build' as const

  isBuilt = false
  constructor(
    name: string,
    config: ResolvedConfig,
    setup?: {
      options?: EnvironmentOptions
    },
  ) {
    let options = config.environments[name]
    if (!options) {
      throw new Error(`Environment "${name}" is not defined in the config.`)
    }
    if (setup?.options) {
      options = mergeConfig(
        options,
        setup.options,
      ) as ResolvedEnvironmentOptions
    }
    super(name, config, options)
  }

  async init(): Promise<void> {
    if (this._initiated) {
      return
    }
    this._initiated = true
  }
}

View on GitHub (pinned to b4d66fee14)