evanw/esbuild · error · Error

Invalid gzip data in archive: ${err && err.message || err}

Error message

Invalid gzip data in archive: ${err && err.message || err}

What it means

`extractFileFromTarGzip` (`node-install.ts:88`) decompresses the npm tarball with `zlib.unzipSync`; if that throws, the downloaded `.tgz` is not valid gzip. The catch wraps the zlib error and rethrows a clearer message. This is the fallback path used when the optional platform package wasn't installed via npm.

Source

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

function fetch(url: string): Promise<Buffer> {
  return new Promise((resolve, reject) => {
    https.get(url, res => {
      if ((res.statusCode === 301 || res.statusCode === 302) && res.headers.location)
        return fetch(res.headers.location).then(resolve, reject)
      if (res.statusCode !== 200)
        return reject(new Error(`Server responded with ${res.statusCode}`))
      let chunks: Buffer[] = []
      res.on('data', chunk => chunks.push(chunk))
      res.on('end', () => resolve(Buffer.concat(chunks)))
    }).on('error', reject)
  })
}

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.

View on GitHub (pinned to 6ff1d8b0d8)

Solutions

1. Retry the install on a stable network connection (the failure is usually transient corruption).
2. Check that your registry config (`npm config get registry`) points at a real npm-compatible registry that serves valid tarballs.
3. Disable proxies/MITM that rewrite npm traffic, or configure them to pass the registry through.
4. Use `npm install` without `--no-optional` so the normal optionalDependencies path is used and the fallback downloader is never invoked.
5. Verify the tarball manually: `curl -sI <url>` should report 200 and `Content-Type: application/octet-stream`.

Example fix

# before
npm install --no-optional esbuild  # forces broken fallback path

# after
npm install esbuild  # uses optionalDependencies normally

import { gunzipSync } from 'zlib'
function looksLikeValidGzip(buf: Buffer): boolean {
  return buf.length > 2 && buf[0] === 0x1f && buf[1] === 0x8b
}
// before passing to a tarball extractor:
if (!looksLikeValidGzip(downloaded)) throw new Error('download is not gzip')

When it happens

Trigger: The fallback downloader (`downloadDirectlyFromNPM`) fetches `https://registry.npmjs.org/.../-/....tgz` and the response body cannot be gunzipped. This path runs only when the optional `@esbuild/<platform>` package is missing AND the nested `npm install` workaround also failed.

Common situations: Corporate proxy/MITM returning an HTML error page instead of the tarball; corrupted download from a flaky registry mirror; npm registry returning a 200 with an error body; running offline with a partial cache; antivirus mangling the byte stream.

Related errors

• Could not find ${JSON.stringify(subpath)} in archive
• 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/be445a61ad9c0621.json. Report an issue: GitHub.