evanw/esbuild · error · Error

Could not find ${JSON.stringify(subpath)} in archive

Error message

Could not find ${JSON.stringify(subpath)} in archive

What it means

After successfully gunzipping the npm tarball, `extractFileFromTarGzip` (`node-install.ts:102`) walks the tar entries looking for `package/<subpath>` (e.g. `package/bin/esbuild`). If no tar entry with that name exists, the requested file isn't in the package — usually meaning the version mismatch between the JS package and the published binary package.

Source

Thrown at lib/npm/node-install.ts:102

function extractFileFromTarGzip(buffer: Buffer, subpath: string): Buffer {
  try {
    buffer = zlib.unzipSync(buffer)
  } catch (err: any) {
    throw new Error(`Invalid gzip data in archive: ${err && err.message || err}`)
  }
  let str = (i: number, n: number) => String.fromCharCode(...buffer.subarray(i, i + n)).replace(/\0.*$/, '')
  let offset = 0
  subpath = `package/${subpath}`
  while (offset < buffer.length) {
    let name = str(offset, 100)
    let size = parseInt(str(offset + 124, 12), 8)
    offset += 512
    if (!isNaN(size) && size >= 0) {
      if (name === subpath) return buffer.subarray(offset, offset + size)
      offset += (size + 511) & ~511
    }
  }
  throw new Error(`Could not find ${JSON.stringify(subpath)} in archive`)
}

function installUsingNPM(pkg: string, subpath: string, binPath: string): void {
  // Erase "npm_config_global" so that "npm install --global esbuild" works.
  // Otherwise this nested "npm install" will also be global, and the install
  // will deadlock waiting for the global installation lock.
  const env = { ...process.env, npm_config_global: undefined }

  // Create a temporary directory inside the "esbuild" package with an empty
  // "package.json" file. We'll use this to run "npm install" in.
  const esbuildLibDir = path.dirname(require.resolve('esbuild'))
  const installDir = path.join(esbuildLibDir, 'npm-install')
  fs.mkdirSync(installDir)
  try {
    fs.writeFileSync(path.join(installDir, 'package.json'), '{}')

    // Run "npm install" in the temporary directory which should download the
    // desired package. Try to avoid unnecessary log output. This uses the "npm"

View on GitHub (pinned to 6ff1d8b0d8)

Solutions

1. Pin esbuild to a known-good version where both JS and binary packages are published (`npm view esbuild@<version>` to confirm).
2. Use a registry mirror that is fully synced with the public npm registry.
3. Stop forcing `--no-optional` so the normal install path resolves the correct binary package directly.
4. If self-hosting, ensure both `esbuild` and the matching `@esbuild/<platform>` are mirrored together.
5. Check `packageJSON['esbuild.binaryHashes']` for the platform key to confirm the version was published correctly.

Example fix

# before
npm install esbuild@latest --no-optional

# after
npm install esbuild@0.25.0  # pinned known-good; uses optionalDependencies

import zlib from 'zlib'
function tarHasEntry(buf: Buffer, subpath: string): boolean {
  const data = zlib.unzipSync(buf)
  const want = `package/${subpath}`
  for (let off = 0; off < data.length; ) {
    const name = String.fromCharCode(...data.subarray(off, off + 100)).replace(/\0.*$/, '')
    if (name === want) return true
    const size = parseInt(String.fromCharCode(...data.subarray(off + 124, off + 136)).replace(/\0.*$/, ''), 8)
    if (isNaN(size)) break
    off += 512 + ((size + 511) & ~511)
  }
  return false
}

When it happens

Trigger: The fallback downloader fetches a tarball whose internal layout doesn't contain the expected binary subpath. Triggered on the same fallback path as error 9 (optionalDependencies missing AND nested npm install failed).

Common situations: Version skew: the JS `packageJSON.version` doesn't correspond to a published `@esbuild/<platform>` tarball (typo in version, yanked publication, private registry mirror out of sync); requesting a binary subpath that doesn't exist for that platform; race during npm publish where the JS package references a not-yet-uploaded binary.

Related errors

• Invalid gzip data in archive: ${err && err.message || err}
• The "esbuild" package cannot be installed because ${os} is t
• Expected ${JSON.stringify(packageJSON.version)} but got ${JS
• Missing hash for "${key}"
• Failed to install package "${pkg}"

AI-assisted analysis of evanw/esbuild@6ff1d8b0d8 (2026-08-03). Data as JSON: /data/errors/28177237df314b71.json. Report an issue: GitHub.