Unable to load @cubejs-backend/native, probably your system

Error message

Unable to load @cubejs-backend/native, probably your system (${process.arch}-${process.platform}) with Node.js ${process.version} is not supported.

What it means

@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.

Source

Thrown at packages/cubejs-backend-native/js/index.ts:191

let loadedNative: any = null;

export function loadNative() {
  if (loadedNative) {
    return loadedNative;
  }

  // Development version
  if (fs.existsSync(path.join(__dirname, '/../../index.node'))) {
    loadedNative = require(path.join(__dirname, '/../../index.node'));
    return loadedNative;
  }

  if (fs.existsSync(path.join(__dirname, '/../../native/index.node'))) {
    loadedNative = require(path.join(__dirname, '/../../native/index.node'));
    return loadedNative;
  }

  throw new Error(
    `Unable to load @cubejs-backend/native, probably your system (${process.arch}-${process.platform}) with Node.js ${process.version} is not supported.`,
  );
}

function wrapNativeFunctionWithChannelCallback(
  fn: (extra: any) => unknown | Promise<unknown>,
) {
  return async (extra: any, channel: any) => {
    try {
      const result = await fn(JSON.parse(extra));

      if (process.env.CUBEJS_NATIVE_INTERNAL_DEBUG) {
        console.debug('[js] channel.resolve', {
          result,
        });
      }

      if (!result) {

View on GitHub (pinned to 7d981676b3)

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).

Example fix

// before: after upgrading Node
$ node -v
v23.0.0

// after: use a supported LTS and rebuild
$ nvm install 22 && nvm use 22
$ npm rebuild @cubejs-backend/native

Defensive patterns

Strategy: try-catch

Validate before calling

const fs = require('fs');
const path = require('path');
const bindingPath = path.join(require.resolve('@cubejs-backend/native'), '../../native/index.node');
if (!fs.existsSync(bindingPath)) {
  console.warn(`@cubejs-backend/native prebuild missing for ${process.arch}-${process.platform} on ${process.version}; reinstall or switch platform/Node version`);
}

Try / catch

let nativeModule;
try {
  nativeModule = getNative();
} catch (e) {
  if (/Unable to load @cubejs-backend\/native/.test(e.message)) {
    console.error(`Unsupported platform ${process.arch}-${process.platform} / ${process.version}: reinstall deps or use a supported Node LTS.`);
  } else throw e;
}

Prevention

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.

When it happens

Trigger: Calling native()/getNative() (which call loadNative) on a platform/architecture/Node ABI combination for which no prebuilt index.node binary exists or was installed.

Common situations: 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.

Related errors

AI-assisted analysis of cube-js/cube@7d981676b3 (2026-09-02). Data as JSON: /api/errors/4c4f8d332dd1e9cb. Report an issue: GitHub.