{"record":{"id":"10a978dfbb25127f","repo":"tauri-apps/tauri","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":"error","filePath":"packages/cli/index.js","lineNumber":590,"sourceCode":"  }\n}\n\nif (!nativeBinding) {\n  if (loadErrors.length > 0) {\n    const error = new Error(\n      `Cannot find native binding. ` +\n        `npm has a bug related to optional dependencies (https://github.com/npm/cli/issues/4828). ` +\n        'Please try `npm i` again after removing both package-lock.json and node_modules directory.',\n    )\n    // assign instead of the `new Error(message, { cause })` options form,\n    // which Node < 16.9 silently ignores\n    error.cause = loadErrors.reduce((err, cur) => {\n      cur.cause = err\n      return cur\n    })\n    throw error\n  }\n  throw new Error(`Failed to load native binding`)\n}\n\nmodule.exports = nativeBinding\nmodule.exports.logError = nativeBinding.logError\nmodule.exports.run = nativeBinding.run\n","sourceCodeStart":572,"sourceCodeEnd":596,"githubUrl":"https://github.com/tauri-apps/tauri/blob/2f1cd75b0f3fb72e6870d719bbfeadedcf8ca884/packages/cli/index.js#L572-L596","documentation":"This is the terminal failure of the NAPI-RS loader inside @tauri-apps/cli: after the whole platform/arch chain ran, the module-level nativeBinding is still falsy while loadErrors is empty, so no more specific error can be reported. Unlike its sibling 'Cannot find native binding' error, it carries no cause chain, which itself signals that no load attempt recorded a failure (e.g. an unhandled platform combination or a require path that silently yielded nothing).","triggerScenarios":"Requiring '@tauri-apps/cli' on a platform/arch combination the loader's if/else chain does not actually attempt a load for, or in environments where require is shimmed (Electron sandbox, bundlers) so attempts neither succeed nor throw; also reachable in the WASI force path when errors are only conditionally pushed to loadErrors.","commonSituations":"Exotic or brand-new platform/runtime combos the generated loader predates; bundlers (webpack/esbuild) rewriting dynamic requires; patched or forked cli packages; corrupted installs where module resolution returns a falsy module.","solutions":["Reproduce standalone: node -e \"require('@tauri-apps/cli')\" to see the raw failure outside your toolchain","Clean install: remove node_modules and lockfile, then npm install","Confirm the platform is supported: node -p \"process.platform + ' ' + process.arch\" against the loader's supported matrix; if unsupported, use the WASI build (NAPI_RS_FORCE_WASI=1) or run the CLI via cargo/rustup instead","If a bundler is involved, add @tauri-apps/cli to externals/node_modules lists so its require is untouched","Report upstream with the standalone repro if the platform is listed as supported"],"exampleFix":"// before (bundling the CLI)\nimport { run } from '@tauri-apps/cli'  // loader shimmed -> 'Failed to load native binding'\n\n// after (webpack.config.js)\nmodule.exports = { externals: { '@tauri-apps/cli': 'commonjs @tauri-apps/cli' } }","handlingStrategy":"try-catch","validationCode":"const fs = require('fs')\n// preflight: a platform-specific binding should exist before require\nconst local = `cli.${process.platform}-${process.arch}${isMusl() ? '-musl' : '-gnu'}.node`\nif (!fs.existsSync(require.resolve('@tauri-apps/cli/' + local))) {\n  process.env.NAPI_RS_FORCE_WASI = '1' // opt into the wasm32-wasi fallback\n}","typeGuard":null,"tryCatchPattern":"try {\n  const cli = require('@tauri-apps/cli')\n} catch (e) {\n  if (/Failed to load native binding/.test(e.message)) {\n    // fallback: WASI build, or shell out to a rustup-installed `tauri`\n    const { execSync } = require('child_process')\n    execSync('tauri ' + process.argv.slice(2).join(' '), { stdio: 'inherit' })\n  } else throw e\n}","preventionTips":["Preflight require('@tauri-apps/cli') as its own CI step so failures are obvious and early","Mark @tauri-apps/cli as external in bundlers (webpack externals, esbuild --external) so its require chain stays intact","On unusual platforms set NAPI_RS_FORCE_WASI=1 deliberately to use the WASI binding","Keep node_modules and lockfile in sync with the CLI version"],"tags":["napi-rs","native-binding","loader","installation","compatibility"],"backgroundTag":null,"analyzedSha":"2f1cd75b0f3fb72e6870d719bbfeadedcf8ca884","analyzedAt":"2026-08-16T04:18:42.486Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}