vitejs/vite · critical · Error

Required environments configuration were stripped out in the

Error message

Required environments configuration were stripped out in the config hook

What it means

In resolveConfig (config.ts:1663-1667), Vite asserts that the client environment (and the ssr environment when not building) still exist after config hooks run. These default environments are required and cannot be removed by user config or plugins; if a config hook stripped them, Vite throws.

Source

Thrown at packages/vite/src/node/config.ts:1664

          external: config.ssr?.external,
          noExternal: config.ssr?.noExternal,
        },
      } satisfies EnvironmentOptions,
      {
        resolve: configEnvironmentsSsr.resolve ?? {},
      },
    ).resolve
  }

  if (config.build?.ssrEmitAssets !== undefined) {
    configEnvironmentsSsr ??= {}
    configEnvironmentsSsr.build ??= {}
    configEnvironmentsSsr.build.emitAssets = config.build.ssrEmitAssets
  }

  // The client and ssr environment configs can't be removed by the user in the config hook
  if (!config.environments.client || (!config.environments.ssr && !isBuild)) {
    throw new Error(
      'Required environments configuration were stripped out in the config hook',
    )
  }

  // Merge default environment config values
  const defaultEnvironmentOptions = getDefaultEnvironmentOptions(config)
  // Some top level options only apply to the client environment
  const defaultClientEnvironmentOptions: UserConfig = {
    ...defaultEnvironmentOptions,
    input: config.input,
    resolve: config.resolve, // inherit everything including mainFields and conditions
    optimizeDeps: config.optimizeDeps,
  }
  const defaultNonClientEnvironmentOptions: UserConfig = {
    ...defaultEnvironmentOptions,
    dev: {
      ...defaultEnvironmentOptions.dev,
      createEnvironment: undefined,

View on GitHub (pinned to 89620f09af)

Solutions

1. Make config hooks extend environments rather than replace — always keep environments.client (and ssr for serve).
2. Return only the new/changed environment keys from the config hook so Vite merges them.
3. If you must reshape environments, re-add client and ssr explicitly.

Example fix

// before (plugin config hook)
config() { return { environments: { custom: { ... } } } } // dropped client/ssr
// after
config() { return { environments: { custom: { ... } } } } // but ensure resolveConfig still sees client/ssr — i.e., don't overwrite the whole map; merge instead

const resolved = await resolveConfig(config, 'serve')
if (!resolved.environments.client || (!resolved.environments.ssr && !isBuild)) {
  throw new Error('Required environments were stripped — fix config hooks')
}

function hasRequiredEnvironments(config: ResolvedConfig, isBuild: boolean): boolean {
  return Boolean(config.environments.client) &&
    (isBuild || Boolean(config.environments.ssr))
}

When it happens

Trigger: A plugin's config() hook (or a returned config merge) that deletes or overrides environments such that environments.client (or environments.ssr in dev) is missing.

Common situations: A plugin that returns { environments: { ... } } omitting client/ssr; merging configs that replace rather than extend environments; experimental environment manipulation gone wrong.

Related errors

• Invalid environment name "${name}". Environment names must o
• No environment found
• FetchableDevEnvironment requires a `handleRequest` method du
• `renderLegacyChunks` and `renderModernChunks` cannot be both
• Environment "${name}" is not defined in the config.

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