evanw/esbuild · critical · Error

Missing hash for "${key}"

Error message

Missing hash for "${key}"

What it means

`binaryIntegrityCheck` (`node-install.ts:232`) sha256-hashes the downloaded binary and looks up the expected hash under `${pkg}/${subpath}` in `packageJSON['esbuild.binaryHashes']`. If that key isn't present, the JS package itself doesn't know what hash to expect — meaning the published JS package was assembled without registering that binary subpath.

Source

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

      // executable instead of a JavaScript file.
      isToPathJS = false

      // If this install script is being re-run, then "renameSync" will fail
      // since the underlying inode is the same (it just returns without doing
      // anything, and without throwing an error). In that case we should remove
      // the file manually.
      fs.unlinkSync(tempPath)
    } catch {
      // Ignore errors here since this optimization is optional
    }
  }
}

function binaryIntegrityCheck(pkg: string, subpath: string, bytes: Uint8Array): void {
  const hash = crypto.createHash('sha256').update(bytes).digest('hex')
  const key = `${pkg}/${subpath}`
  const expected = packageJSON['esbuild.binaryHashes'][key]
  if (!expected) throw new Error(`Missing hash for "${key}"`)
  if (hash !== expected) throw new Error(`"${hash.slice(0, 8)}..." doesn't match "${expected.slice(0, 8)}..." for "${pkg}"`)
}

async function downloadDirectlyFromNPM(pkg: string, subpath: string, binPath: string): Promise<void> {
  // If that fails, the user could have npm configured incorrectly or could not
  // have npm installed. Try downloading directly from npm as a last resort.
  const url = `https://registry.npmjs.org/${pkg}/-/${pkg.replace('@esbuild/', '')}-${packageJSON.version}.tgz`
  console.error(`[esbuild] Trying to download ${JSON.stringify(url)}`)
  try {
    const bytes = extractFileFromTarGzip(await fetch(url), subpath)
    binaryIntegrityCheck(pkg, subpath, bytes)
    fs.writeFileSync(binPath, bytes)
    fs.chmodSync(binPath, 0o755)
  } catch (e: any) {
    console.error(`[esbuild] Failed to download ${JSON.stringify(url)}: ${e && e.message || e}`)
    throw e
  }
}

View on GitHub (pinned to 6ff1d8b0d8)

Solutions

1. Upgrade to a released esbuild version where the binaryHashes map is complete for your platform.
2. Downgrade to a version known to support your platform.
3. If you're a fork maintainer, ensure `esbuild.binaryHashes` includes every `(pkg, subpath)` you reference in `knownUnixlikePackages`/`knownWindowsPackages`/`knownWebAssemblyFallbackPackages`.
4. Report the missing hash upstream with the exact esbuild version and platform key.

Example fix

// npm/esbuild/package.json (fork fix)
// before
"esbuild.binaryHashes": { "@esbuild/linux-x64/bin/esbuild": "abc..." }

// after
"esbuild.binaryHashes": {
  "@esbuild/linux-x64/bin/esbuild": "abc...",
  "@esbuild/linux-loong64/bin/esbuild": "def..."
}

import hashes from 'esbuild/package.json'
function platformHashKnown(pkg: string, subpath: string): boolean {
  return !!hashes['esbuild.binaryHashes']?.[`${pkg}/${subpath}`]
}

When it happens

Trigger: The install fallback path runs `binaryIntegrityCheck` for a `(pkg, subpath)` pair whose key is absent from the `esbuild.binaryHashes` map inside `npm/esbuild/package.json`. The integrity check refuses to proceed without a known-good hash.

Common situations: A new platform package (e.g. `@esbuild/linux-loong64`) was added to `knownUnixlikePackages` but the release didn't update `esbuild.binaryHashes`; user is on an unreleased/RC build; the package.json was patched by a fork that added a platform key without the hash; corrupted or partially-overwritten package.json.

Related errors

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

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