{"record":{"id":"4c4f8d332dd1e9cb","repo":"cube-js/cube","slug":"unable-to-load-cubejs-backend-native-probably-yo","errorCode":null,"errorMessage":"Unable to load @cubejs-backend/native, probably your system (${process.arch}-${process.platform}) with Node.js ${process.version} is not supported.","messagePattern":"Unable to load @cubejs-backend/native, probably your system \\((.+?)-(.+?)\\) with Node\\.js (.+?) is not supported\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"packages/cubejs-backend-native/js/index.ts","lineNumber":191,"sourceCode":"let loadedNative: any = null;\n\nexport function loadNative() {\n  if (loadedNative) {\n    return loadedNative;\n  }\n\n  // Development version\n  if (fs.existsSync(path.join(__dirname, '/../../index.node'))) {\n    loadedNative = require(path.join(__dirname, '/../../index.node'));\n    return loadedNative;\n  }\n\n  if (fs.existsSync(path.join(__dirname, '/../../native/index.node'))) {\n    loadedNative = require(path.join(__dirname, '/../../native/index.node'));\n    return loadedNative;\n  }\n\n  throw new Error(\n    `Unable to load @cubejs-backend/native, probably your system (${process.arch}-${process.platform}) with Node.js ${process.version} is not supported.`,\n  );\n}\n\nfunction wrapNativeFunctionWithChannelCallback(\n  fn: (extra: any) => unknown | Promise<unknown>,\n) {\n  return async (extra: any, channel: any) => {\n    try {\n      const result = await fn(JSON.parse(extra));\n\n      if (process.env.CUBEJS_NATIVE_INTERNAL_DEBUG) {\n        console.debug('[js] channel.resolve', {\n          result,\n        });\n      }\n\n      if (!result) {","sourceCodeStart":173,"sourceCodeEnd":209,"githubUrl":"https://github.com/cube-js/cube/blob/7d981676b36392fec34088b9afab6bdcad40207c/packages/cubejs-backend-native/js/index.ts#L173-L209","documentation":"@cubejs-backend-native wraps a precompiled native addon (index.node). loadNative tries to require the compiled binary, and if it is absent (the platform-specific prebuild was not shipped or installed) it throws with the system arch/platform and Node version so the developer knows why it is unsupported.","triggerScenarios":"Calling native()/getNative() (which call loadNative) on a platform/architecture/Node ABI combination for which no prebuilt index.node binary exists or was installed.","commonSituations":"Uncommon platforms (Alpine/musl, ARM variants, FreeBSD), Node version major upgrade changing the ABI (e.g. Node 18 → 22) without reinstalling, npm install skipping build scripts (--ignore-scripts), partial/corrupted install where the native folder is missing.","solutions":["Reinstall the package so platform prebuilds are fetched: `npm rebuild @cubejs-backend/native` or delete node_modules and `npm install`.","Check the supported platform matrix — move to a supported OS/arch/Node LTS combination.","Ensure install scripts are not disabled (remove --ignore-scripts / set ignore-scripts=false).","Match the Node.js version to one with published prebuilds (use nvm to switch)."],"exampleFix":"// before: after upgrading Node\n$ node -v\nv23.0.0\n\n// after: use a supported LTS and rebuild\n$ nvm install 22 && nvm use 22\n$ npm rebuild @cubejs-backend/native","handlingStrategy":"try-catch","validationCode":"const fs = require('fs');\nconst path = require('path');\nconst bindingPath = path.join(require.resolve('@cubejs-backend/native'), '../../native/index.node');\nif (!fs.existsSync(bindingPath)) {\n  console.warn(`@cubejs-backend/native prebuild missing for ${process.arch}-${process.platform} on ${process.version}; reinstall or switch platform/Node version`);\n}","typeGuard":null,"tryCatchPattern":"let nativeModule;\ntry {\n  nativeModule = getNative();\n} catch (e) {\n  if (/Unable to load @cubejs-backend\\/native/.test(e.message)) {\n    console.error(`Unsupported platform ${process.arch}-${process.platform} / ${process.version}: reinstall deps or use a supported Node LTS.`);\n  } else throw e;\n}","preventionTips":["Pin your CI/runtime to a Node LTS with published prebuilds for your OS/arch.","Never install with --ignore-scripts; rebuild after Node major upgrades (npm rebuild).","Check the supported platform matrix before deploying to Alpine/ARM images."],"tags":["native-addon","platform-compatibility","node-abi","installation"],"backgroundTag":"native-binding-not-found","analyzedSha":"7d981676b36392fec34088b9afab6bdcad40207c","analyzedAt":"2026-09-02T03:45:10.400Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}