vitejs/vite · error · Error

Invalid environment name "${name}". Environment names must o

Error message

Invalid environment name "${name}". Environment names must only contain alphanumeric characters and "$", "_".

What it means

Vite validates environment names against /^\w+$/ in the PartialEnvironment constructor (baseEnvironment.ts:39). Names are restricted to alphanumerics, underscore, and dollar sign so they can be used unescaped as directory names and accessed safely via environments.*. Any other character (hyphen, dot, space, slash) is rejected when the environment is constructed.

Source

Thrown at packages/vite/src/node/baseEnvironment.ts:40

  /**
   * @internal
   */
  _options: ResolvedEnvironmentOptions
  /**
   * @internal
   */
  _topLevelConfig: ResolvedConfig

  constructor(
    name: string,
    topLevelConfig: ResolvedConfig,
    options: ResolvedEnvironmentOptions = topLevelConfig.environments[name],
  ) {
    // only allow some characters so that we can use name without escaping for directory names
    // and make users easier to access with `environments.*`
    if (!/^[\w$]+$/.test(name)) {
      throw new Error(
        `Invalid environment name "${name}". Environment names must only contain alphanumeric characters and "$", "_".`,
      )
    }
    this.name = name
    this._topLevelConfig = topLevelConfig
    this._options = options
    this.config = new Proxy(
      options as ResolvedConfig & ResolvedEnvironmentOptions,
      {
        get: (target, prop: keyof ResolvedConfig) => {
          if (prop === 'logger') {
            return this.logger
          }
          if (prop in target) {
            return this._options[prop as keyof ResolvedEnvironmentOptions]
          }
          return this._topLevelConfig[prop]
        },

View on GitHub (pinned to 89620f09af)

Solutions

1. Rename the environment to use only [A-Za-z0-9_$], e.g. 'myApp' or 'ssr_client'.
2. If the name is derived dynamically, sanitize it against /^\w+$/ before use.
3. Audit config keys and plugin code that constructs environments for stray punctuation.

Example fix

// before
environments: { 'ssr-client': { ... } }
// after
environments: { ssrClient: { ... } }

const ENV_NAME_RE = /^[\w$]+$/
function safeEnvName(name: string): string {
  if (!ENV_NAME_RE.test(name)) {
    throw new Error(`Invalid environment name: ${name}`)
  }
  return name
}

function isValidEnvironmentName(name: string): boolean {
  return /^[\w$]+$/.test(name)
}

When it happens

Trigger: Registering or constructing an environment (BaseEnvironment/PartialEnvironment, or via the environments config map) with a name like 'my-env', 'ssr.client', 'client v2', or 'ssr/worker'.

Common situations: Naming a custom environment in vite.config under environments: { 'my-app': {...} }; passing a hyphenated or dotted key when programmatically creating a dev/build environment; deriving the name from an OS variable that contains slashes.

Related errors

• Required environments configuration were stripped out in the
• FetchableDevEnvironment requires a `handleRequest` method du
• `renderLegacyChunks` and `renderModernChunks` cannot be both
• No environment found
• Environment "${name}" is not defined in the config.

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