evanw/esbuild · error · Error

Invalid gzip data in archive

Error message

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

What it means

When the postinstall falls back to downloading the native package directly from the npm registry (downloadDirectlyFromNPM, lib/npm/node-install.ts:236), extractFileFromTarGzip() calls zlib.unzipSync on the response body. If decompression fails, the raw zlib error is wrapped in this message (lib/npm/node-install.ts:88). It means the bytes received were not a valid gzip stream.

Solutions

1. Retry the install (transient network/CDN errors often clear).
2. Clear the package manager cache and reinstall.
3. Check proxy/registry configuration; ensure the mirror serves the raw .tgz untouched.
4. Remove --no-optional so the normal optionalDependencies path is used instead of the HTTP fallback.

// Pre-flight: confirm the registry tarball is a valid gzip before relying on it.
const zlib = require('zlib')
function isValidGzip(buf) {
  try { zlib.unzipSync(buf); return true } catch { return false }
}
// fetch the .tgz, then: if (!isValidGzip(buf)) retry / abort with a clear message

// Retry transient download corruption a few times before giving up.
async function fetchWithRetry(url, attempts = 3) {
  let lastErr
  for (let i = 0; i < attempts; i++) {
    try { return await fetch(url) }
    catch (e) { lastErr = e }
  }
  throw lastErr
}

When it happens

Trigger: The fallback HTTP download of the @esbuild/* .tgz returns a body that is truncated or not valid gzip, so zlib.unzipSync throws.

Common situations: Flaky network causing a truncated transfer; a corporate proxy rewriting/compressing bytes; a misconfigured npm registry mirror returning HTML errors with a 200; corrupted intermediate cache; registry CDN serving a partial file.

Related errors

• Could not find in archive
• Failed to download
• Cannot start service: Host version
• Expected but got
• Failed to install package

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

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