evanw/esbuild · error · Error

Invalid package name in alias

Error message

Invalid package name in alias: ${old}

What it means

The `alias` option is serialized as `--alias:OLD=NEW`. An '=' inside the OLD package name breaks parsing, so esbuild rejects such alias keys at lib/shared/common.ts:316.

Solutions

1. Remove '=' from the alias key (use the bare package/package-path name).
2. For subpath aliasing, use a plugin or alias the base package and re-export.

Example fix

// before
await build({ entryPoints: ['app.ts'], alias: { 'lib=util': 'shim' } })

// after
await build({ entryPoints: ['app.ts'], alias: { 'lib': 'shim' } })

function assertAliasKeys(map) {
  for (const k of Object.keys(map ?? {})) {
    if (k.includes('=')) throw new Error(`alias key must not contain '=': ${k}`)
  }
}
assertAliasKeys(options.alias)

When it happens

Trigger: Passing `alias: { 'pkg=subpath': 'other' }` or any alias key (old package name) containing '='.

Common situations: Trying to alias a subpath import using '=' in the key instead of esbuild's subpath rules; templated alias names that embed '='.

Related errors

• Expected in mangle cache to map to either a string or false
• Expected value for supported
• Expected value for to be a string, got instead
• Invalid banner file type
• Invalid charset

AI-assisted analysis of evanw/esbuild@f6058f8364 (2026-08-09). Data as JSON: /api/errors/920a667dfc09a287. Report an issue: GitHub.

Appendix: source

Thrown at lib/shared/common.ts:316

  if (splitting) flags.push('--splitting')
  if (preserveSymlinks) flags.push('--preserve-symlinks')
  if (metafile) flags.push(`--metafile`)
  if (outfile) flags.push(`--outfile=${outfile}`)
  if (outdir) flags.push(`--outdir=${outdir}`)
  if (outbase) flags.push(`--outbase=${outbase}`)
  if (tsconfig) flags.push(`--tsconfig=${tsconfig}`)
  if (packages) flags.push(`--packages=${packages}`)
  if (resolveExtensions) flags.push(`--resolve-extensions=${validateAndJoinStringArray(resolveExtensions, 'resolve extension')}`)
  if (publicPath) flags.push(`--public-path=${publicPath}`)
  if (entryNames) flags.push(`--entry-names=${entryNames}`)
  if (chunkNames) flags.push(`--chunk-names=${chunkNames}`)
  if (assetNames) flags.push(`--asset-names=${assetNames}`)
  if (mainFields) flags.push(`--main-fields=${validateAndJoinStringArray(mainFields, 'main field')}`)
  if (conditions) flags.push(`--conditions=${validateAndJoinStringArray(conditions, 'condition')}`)
  if (external) for (let name of external) flags.push(`--external:${validateStringValue(name, 'external')}`)
  if (alias) {
    for (let old in alias) {
      if (old.indexOf('=') >= 0) throw new Error(`Invalid package name in alias: ${old}`)
      flags.push(`--alias:${old}=${validateStringValue(alias[old], 'alias', old)}`)
    }
  }
  if (banner) {
    for (let type in banner) {
      if (type.indexOf('=') >= 0) throw new Error(`Invalid banner file type: ${type}`)
      flags.push(`--banner:${type}=${validateStringValue(banner[type], 'banner', type)}`)
    }
  }
  if (footer) {
    for (let type in footer) {
      if (type.indexOf('=') >= 0) throw new Error(`Invalid footer file type: ${type}`)
      flags.push(`--footer:${type}=${validateStringValue(footer[type], 'footer', type)}`)
    }
  }
  if (inject) for (let path of inject) flags.push(`--inject:${validateStringValue(path, 'inject')}`)
  if (loader) {
    for (let ext in loader) {

View on GitHub (pinned to f6058f8364)