vitejs/vite · error · Error

Required environments configuration were stripped out in…

Error message

Required environments configuration were stripped out in the config hook

What it means

Vite guarantees that a resolved config always carries environments.client and (for non-build/serve flows) environments.ssr. After user plugins run the config hook, the resolver checks these still exist; if a plugin deleted them the build is unsafe, so it throws. This is a safety net against misbehaving plugins.

Solutions

Fix the offending plugin to merge rather than replace config.environments.
Ensure the config hook returns { environments: { client: { ... }, ssr: { ... }, ...yours } }.
Update or remove plugins that mutate environments incompatibly.

Example fix

// before (plugin config hook)
config: () => ({ environments: { worker: { ... } } }) // strips client/ssr
// after
config: (cfg) => ({ environments: { ...cfg.environments, worker: { ... } } })

Defensive patterns

Strategy: validation

Validate before calling

function validateEnvironmentsIntact(newConfig, oldConfig) {
  const required = ['client'];
  return required.filter((k) => !newConfig?.environments?.[k]);
}

Type guard

function configHasRequiredEnvironments(config, isBuild) {
  return Boolean(config?.environments?.client && (isBuild || config.environments.ssr));
}

Prevention

Merge into config.environments in plugin hooks, never replace it.
Test plugins that mutate environments against a real build.

When it happens

Trigger: A plugin's config or configResolved hook returns a config object without environments.client (or environments.ssr in serve mode), effectively stripping the default environments. Also triggered by plugins that replace config.environments wholesale with an object missing those keys.

Common situations: Plugin authors who return { environments: { ...customOnly } } from the config hook, accidentally omitting client/ssr; custom environment-management plugins that mis-handle the defaults.

Related errors

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

Appendix: 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 b4d66fee14)