{"id":"28177237df314b71","repo":"evanw/esbuild","slug":"could-not-find-json-stringify-subpath-in-archi","errorCode":null,"errorMessage":"Could not find ${JSON.stringify(subpath)} in archive","messagePattern":"Could not find (.+?) in archive","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/npm/node-install.ts","lineNumber":102,"sourceCode":"function 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.\n  // Otherwise this nested \"npm install\" will also be global, and the install\n  // will deadlock waiting for the global installation lock.\n  const env = { ...process.env, npm_config_global: undefined }\n\n  // Create a temporary directory inside the \"esbuild\" package with an empty\n  // \"package.json\" file. We'll use this to run \"npm install\" in.\n  const esbuildLibDir = path.dirname(require.resolve('esbuild'))\n  const installDir = path.join(esbuildLibDir, 'npm-install')\n  fs.mkdirSync(installDir)\n  try {\n    fs.writeFileSync(path.join(installDir, 'package.json'), '{}')\n\n    // Run \"npm install\" in the temporary directory which should download the\n    // desired package. Try to avoid unnecessary log output. This uses the \"npm\"","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/evanw/esbuild/blob/6ff1d8b0d8c134e867a397eef39702a223ebef9e/lib/npm/node-install.ts#L84-L120","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Pin esbuild to a known-good version where both JS and binary packages are published (`npm view esbuild@<version>` to confirm).","Use a registry mirror that is fully synced with the public npm registry.","Stop forcing `--no-optional` so the normal install path resolves the correct binary package directly.","If self-hosting, ensure both `esbuild` and the matching `@esbuild/<platform>` are mirrored together.","Check `packageJSON['esbuild.binaryHashes']` for the platform key to confirm the version was published correctly."],"exampleFix":"# before\nnpm install esbuild@latest --no-optional\n\n# after\nnpm install esbuild@0.25.0  # pinned known-good; uses optionalDependencies","handlingStrategy":"validation","validationCode":"import zlib from 'zlib'\nfunction tarHasEntry(buf: Buffer, subpath: string): boolean {\n  const data = zlib.unzipSync(buf)\n  const want = `package/${subpath}`\n  for (let off = 0; off < data.length; ) {\n    const name = String.fromCharCode(...data.subarray(off, off + 100)).replace(/\\0.*$/, '')\n    if (name === want) return true\n    const size = parseInt(String.fromCharCode(...data.subarray(off + 124, off + 136)).replace(/\\0.*$/, ''), 8)\n    if (isNaN(size)) break\n    off += 512 + ((size + 511) & ~511)\n  }\n  return false\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pin esbuild to versions where both JS and binary packages are published.","Use a fully-synced registry mirror.","Avoid --no-optional so the normal install path is used.","Verify `packageJSON['esbuild.binaryHashes']` contains your platform key before trusting a version."],"tags":["install","registry","version-skew","tarball","fallback"],"analyzedSha":"6ff1d8b0d8c134e867a397eef39702a223ebef9e","analyzedAt":"2026-08-03T19:42:38.433Z","schemaVersion":2}