{"record":{"id":"94a9731e3aff8a4d","repo":"parcel-bundler/parcel","slug":"failed-to-load-native-binding","errorCode":null,"errorMessage":"Failed to load native binding","messagePattern":"Failed to load native binding","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/core/rust/index.js","lineNumber":323,"sourceCode":"            nativeBinding = require('@parcel/rust-linux-s390x-gnu');\n          }\n        } catch (e) {\n          loadError = e;\n        }\n        break;\n      default:\n        throw new Error(`Unsupported architecture on Linux: ${arch}`);\n    }\n    break;\n  default:\n    throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`);\n}\n\nif (!nativeBinding) {\n  if (loadError) {\n    throw loadError;\n  }\n  throw new Error(`Failed to load native binding`);\n}\n\nconst {\n  findAncestorFile,\n  findFirstFile,\n  findNodeModule,\n  hashString,\n  hashBuffer,\n  Hash,\n  optimizeImage,\n  transformHtml,\n  packageHtml,\n  optimizeHtml,\n  transformSvg,\n  packageSvg,\n  optimizeSvg,\n  svgReact,\n  Resolver,","sourceCodeStart":305,"sourceCodeEnd":341,"githubUrl":"https://github.com/parcel-bundler/parcel/blob/59484858a1a0bcbb71f74088956bb437a2db6505/packages/core/rust/index.js#L305-L341","documentation":"Thrown by @parcel/rust's binding loader after the platform/arch switch when nativeBinding is still falsy AND no loadError was captured. It indicates the loader never assigned a binding (a logic/coverage gap) rather than a require() failure, which would have surfaced via loadError instead.","triggerScenarios":"Control flow reaches the post-switch guard with nativeBinding unset because a case branch returned early without assigning and without throwing — e.g. a missing break assignment path, or a future platform case added without populating nativeBinding.","commonSituations":"Seen after partial installs where the correct @parcel/rust-<platform-arch> optional dependency was skipped (npm --no-optional) but the local .node file also absent; or a packaging bug where the case exists but both localFileExisted and the package require were bypassed.","solutions":["Reinstall dependencies with optional deps enabled: `npm ci` (do not pass --no-optional).","Verify the local prebuilt .node file or the @parcel/rust-<platform-arch> package is present in node_modules.","Clear npm cache and node_modules (`rm -rf node_modules package-lock.json && npm i`).","If persistent, file an upstream issue — this code path implies a loader bug worth reporting with platform/arch details."],"exampleFix":"# before\n$ npm install --no-optional   # prebuilt skipped -> nativeBinding never set\n\n# after\n$ npm ci   # optionalDependencies install the platform binding","handlingStrategy":"validation","validationCode":"// After install, assert the platform binding is present before importing @parcel/rust.\nconst { platform, arch } = require('process');\nconst fs = require('fs');\nconst path = require('path');\nconst bindingDir = path.dirname(require.resolve('@parcel/rust/package.json'));\nconst hasBinding = fs.readdirSync(bindingDir)\n  .some(f => f.includes(`${platform}-${arch}`));\nif (!hasBinding) {\n  throw new Error('No native binding installed; run `npm ci` without --no-optional.');\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never install with --no-optional; the platform binding is an optionalDependency.","After install, verify node_modules/@parcel/rust-<platform-arch> exists.","Pin lockfile and use `npm ci` in CI for reproducible optional dep resolution."],"tags":["native-binding","parcel-rust","installation","optional-deps"],"backgroundTag":null,"analyzedSha":"59484858a1a0bcbb71f74088956bb437a2db6505","analyzedAt":"2026-08-13T04:06:35.925Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}