{"record":{"id":"0b3f6d50902caaf5","repo":"evanw/esbuild","slug":"cannot-start-service-host-version-esbuild-vers","errorCode":null,"errorMessage":"Cannot start service: Host version \"${ESBUILD_VERSION}\" does not match binary version ${quote(binaryVersion)}","messagePattern":"Cannot start service: Host version \"(.+?)\" does not match binary version (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"lib/shared/common.ts","lineNumber":623,"sourceCode":"        // cause an unhandled promise rejection. Our caller isn't expecting\n        // this call to fail and doesn't handle the promise rejection.\n      }\n    }\n  }\n\n  let isFirstPacket = true\n\n  let handleIncomingPacket = (bytes: Uint8Array<ArrayBuffer>): void => {\n    // The first packet is a version check\n    if (isFirstPacket) {\n      isFirstPacket = false\n\n      // Validate the binary's version number to make sure esbuild was installed\n      // correctly. This check was added because some people have reported\n      // errors that appear to indicate an incorrect installation.\n      let binaryVersion = String.fromCharCode(...bytes)\n      if (binaryVersion !== ESBUILD_VERSION) {\n        throw new Error(`Cannot start service: Host version \"${ESBUILD_VERSION}\" does not match binary version ${quote(binaryVersion)}`)\n      }\n      return\n    }\n\n    let packet = protocol.decodePacket(bytes) as any\n\n    if (packet.isRequest) {\n      handleRequest(packet.id, packet.value)\n    }\n\n    else {\n      let callback = responseCallbacks[packet.id]!\n      delete responseCallbacks[packet.id]\n      if (packet.value.error) callback(packet.value.error, {})\n      else callback(null, packet.value)\n    }\n  }\n","sourceCodeStart":605,"sourceCodeEnd":641,"githubUrl":"https://github.com/evanw/esbuild/blob/f6058f8364fe7ab91ca57a83e02577ed74c9cae4/lib/shared/common.ts#L605-L641","documentation":"On the first packet from the spawned esbuild binary, the JS wrapper compares the binary's self-reported version against the JS-side ESBUILD_VERSION constant (lib/shared/common.ts:622). Any mismatch aborts service startup. This guard detects broken installs where the native binary (from a platform package like @esbuild/linux-x64) and the JS wrapper come from different esbuild releases.","triggerScenarios":"Any esbuild API call (build/transform/context) that starts the service when the installed `esbuild` JS package version differs from the installed platform-binary package version. The message prints both versions for diagnosis.","commonSituations":"A partial/half-upgraded install (lockfile resolved esbuild to one version and @esbuild/<platform> to another); duplicate esbuild copies in a monorepo (hoisting); stale npm/yarn/pnpm cache or PnP mismatch; manually copied esbuild binaries; CI caching node_modules across an upgrade.","solutions":["Delete node_modules and the lockfile, then reinstall cleanly so esbuild and all @esbuild/* platform packages align to one version.","Run your package manager's dedupe (npm dedupe / yarn dedupe / pnpm dedupe) to collapse duplicate esbuild versions.","Pin esbuild to a single exact version in package.json and ensure transitive deps don't pull in a different one (npm ls esbuild).","Clear CI caches that snapshot node_modules across version bumps."],"exampleFix":"# before: mismatched versions in lockfile\nnpm ls esbuild      # shows multiple versions\n\n# after\nrm -rf node_modules package-lock.json\nnpm install esbuild@latest\nnpm ls esbuild      # single version","handlingStrategy":"try-catch","validationCode":"import { version as jsVersion } from 'esbuild'\n// Fail fast in your own setup if a platform binary is missing/mismatched\nimport { existsSync } from 'fs'\n// Example: sanity-check that the platform package resolves\nfunction preflight() {\n  try {\n    require.resolve('@esbuild/linux-x64/bin/esbuild') // adjust to your platform\n  } catch {\n    throw new Error('esbuild platform binary not installed; run a clean install')\n  }\n}\npreflight()","typeGuard":null,"tryCatchPattern":"try {\n  await esbuild.build(opts)\n} catch (e) {\n  if (/does not match binary version/.test(e.message)) {\n    console.error('esbuild version mismatch detected. Run: rm -rf node_modules package-lock.json && npm install')\n    process.exit(1)\n  }\n  throw e\n}","preventionTips":["Pin esbuild to a single exact version in package.json and run `npm ls esbuild` in CI to detect duplicates.","Run `npm dedupe` (or pnpm/yarn equivalent) after upgrades.","Don't cache node_modules across an esbuild version bump in CI; bust the cache on dependency changes.","After upgrading esbuild, delete node_modules and the lockfile and reinstall fresh."],"tags":["install","version-mismatch","binary","startup","critical"],"backgroundTag":null,"analyzedSha":"f6058f8364fe7ab91ca57a83e02577ed74c9cae4","analyzedAt":"2026-08-09T18:37:22.223Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}