{"record":{"id":"be445a61ad9c0621","repo":"evanw/esbuild","slug":"invalid-gzip-data-in-archive-err-err-message","errorCode":null,"errorMessage":"Invalid gzip data in archive: ${err && err.message || err}","messagePattern":"Invalid gzip data in archive: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/npm/node-install.ts","lineNumber":88,"sourceCode":"function fetch(url: string): Promise<Buffer> {\n  return new Promise((resolve, reject) => {\n    https.get(url, res => {\n      if ((res.statusCode === 301 || res.statusCode === 302) && res.headers.location)\n        return fetch(res.headers.location).then(resolve, reject)\n      if (res.statusCode !== 200)\n        return reject(new Error(`Server responded with ${res.statusCode}`))\n      let chunks: Buffer[] = []\n      res.on('data', chunk => chunks.push(chunk))\n      res.on('end', () => resolve(Buffer.concat(chunks)))\n    }).on('error', reject)\n  })\n}\n\nfunction extractFileFromTarGzip(buffer: Buffer, subpath: string): Buffer {\n  try {\n    buffer = zlib.unzipSync(buffer)\n  } catch (err: any) {\n    throw new Error(`Invalid gzip data in archive: ${err && err.message || err}`)\n  }\n  let str = (i: number, n: number) => String.fromCharCode(...buffer.subarray(i, i + n)).replace(/\\0.*$/, '')\n  let offset = 0\n  subpath = `package/${subpath}`\n  while (offset < buffer.length) {\n    let name = str(offset, 100)\n    let size = parseInt(str(offset + 124, 12), 8)\n    offset += 512\n    if (!isNaN(size) && size >= 0) {\n      if (name === subpath) return buffer.subarray(offset, offset + size)\n      offset += (size + 511) & ~511\n    }\n  }\n  throw new Error(`Could not find ${JSON.stringify(subpath)} in archive`)\n}\n\nfunction installUsingNPM(pkg: string, subpath: string, binPath: string): void {\n  // Erase \"npm_config_global\" so that \"npm install --global esbuild\" works.","sourceCodeStart":70,"sourceCodeEnd":106,"githubUrl":"https://github.com/evanw/esbuild/blob/f6058f8364fe7ab91ca57a83e02577ed74c9cae4/lib/npm/node-install.ts#L70-L106","documentation":"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.","triggerScenarios":"The fallback HTTP download of the @esbuild/* .tgz returns a body that is truncated or not valid gzip, so zlib.unzipSync throws.","commonSituations":"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.","solutions":["Retry the install (transient network/CDN errors often clear).","Clear the package manager cache and reinstall.","Check proxy/registry configuration; ensure the mirror serves the raw .tgz untouched.","Remove --no-optional so the normal optionalDependencies path is used instead of the HTTP fallback."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// Pre-flight: confirm the registry tarball is a valid gzip before relying on it.\nconst zlib = require('zlib')\nfunction isValidGzip(buf) {\n  try { zlib.unzipSync(buf); return true } catch { return false }\n}\n// fetch the .tgz, then: if (!isValidGzip(buf)) retry / abort with a clear message","typeGuard":null,"tryCatchPattern":"// Retry transient download corruption a few times before giving up.\nasync function fetchWithRetry(url, attempts = 3) {\n  let lastErr\n  for (let i = 0; i < attempts; i++) {\n    try { return await fetch(url) }\n    catch (e) { lastErr = e }\n  }\n  throw lastErr\n}","preventionTips":["Ensure network/proxy does not alter binary tarball bytes.","Use a reliable registry/mirror; clear corrupted caches.","Avoid --no-optional so the normal install path (which doesn't re-download) is used."],"tags":["network","install","download","gzip","registry"],"backgroundTag":null,"analyzedSha":"f6058f8364fe7ab91ca57a83e02577ed74c9cae4","analyzedAt":"2026-08-09T18:37:22.223Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}