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

Declare the environment in config.environments, e.g. environments: { ssr: { ... } }.

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

In the BuildEnvironment constructor (build.ts:1749-1752), Vite looks up config.environments[name]; if that environment isn't defined in the resolved config it throws. Build environments must be declared in the config's environments map before they can be built.

Source

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

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 89620f09af)

Solutions

Declare the environment in config.environments, e.g. environments: { ssr: { ... } }.
Match the environment name used in build tooling exactly to a key in environments.
If the environment was removed intentionally, stop referencing it in build scripts.

Example fix

// before
environments: { client: { ... } }
// build code references 'ssr'
// after
environments: { client: { ... }, ssr: { ... } }

Defensive patterns

Strategy: validation

Validate before calling

const resolved = await resolveConfig(config, 'build')
const names = Object.keys(resolved.environments)
if (!names.includes(targetName)) {
  throw new Error(`Environment '${targetName}' not in config; available: ${names.join(', ')}`)
}

Type guard

function environmentIsDefined(config: ResolvedConfig, name: string): boolean {
  return name in config.environments
}

Prevention

Declare every environment you build under config.environments.
Keep environment names consistent between config and build scripts.
When removing an environment, grep build tooling for stale references.

When it happens

Trigger: Constructing a BuildEnvironment (or triggering a build for one) with a name that has no entry under config.environments — e.g. building environment 'ssr' when only 'client' is configured, or a typo'd name.

Common situations: Adding a custom environment name in build tooling without declaring it in vite.config environments; renaming an environment in one place but not the config; referencing an SSR environment that was disabled.

Related errors

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