cube-js/cube · error

Unable to load Python configuration because you are using th

Error message

Unable to load Python configuration because you are using the fallback build of native extension. Read more: https://github.com/cube-js/cube/blob/master/packages/cubejs-backend-native/README.md#supported-architectures-and-platforms

What it means

Similar to the native-support error: cube.py was found so the Python config bridge is needed, but the installed native extension is a fallback build — one shipped without actual native functionality (e.g. a stub for unsupported platforms). isFallbackBuild() returns true, and Cube refuses to load Python configuration since the bridge cannot work.

Source

Thrown at packages/cubejs-server/src/server/container.ts:280

      multiline: 'line-breaks'
    });

    const devMode = getEnv('devMode');
    if (devMode) {
      process.env.NODE_ENV = 'development';
    }

    if (fs.existsSync(path.join(process.cwd(), 'cube.py'))) {
      const supported = isNativeSupported();
      if (supported !== true) {
        throw new Error(
          `Native extension is required to load Python configuration. ${supported.reason}. Read more: ` +
          'https://github.com/cube-js/cube/blob/master/packages/cubejs-backend-native/README.md#supported-architectures-and-platforms'
        );
      }

      if (isFallbackBuild()) {
        throw new Error(
          'Unable to load Python configuration because you are using the fallback build of native extension. Read more: ' +
          'https://github.com/cube-js/cube/blob/master/packages/cubejs-backend-native/README.md#supported-architectures-and-platforms'
        );
      }

      return this.loadConfigurationFromPythonFile();
    }

    if (fs.existsSync(path.join(process.cwd(), 'cube.ts'))) {
      return this.loadConfigurationFromMemory(
        this.getTypeScriptCompiler().compileConfiguration()
      );
    }

    if (fs.existsSync(path.join(process.cwd(), 'cube.js'))) {
      return this.loadConfigurationFromFile();
    }

View on GitHub (pinned to 7d981676b3)

Solutions

1. Reinstall dependencies on a supported platform so a real native build is installed (rm -rf node_modules && npm install)
2. Check that @cubejs-backend/native resolved to a real build, not the fallback stub
3. Convert configuration from cube.py to cube.js to bypass the native Python bridge entirely
4. Fix the native compilation failure (missing toolchain, glibc vs musl) and rebuild

Example fix

# before
ls node_modules/@cubejs-backend/native  # fallback stub installed

# after
rm -rf node_modules package-lock.json
npm install   # on a supported glibc platform
# or: remove cube.py, use cube.js

const { isNativeSupported, isFallbackBuild } = require('@cubejs-backend/native');
if (fs.existsSync('cube.py')) {
  if (isNativeSupported() !== true || isFallbackBuild()) {
    throw new Error('Real native build required for cube.py config');
  }
}

null

try {
  await server.listen();
} catch (e) {
  if (e.message.includes('fallback build of native extension')) {
    console.error('Reinstall dependencies on a supported platform or use cube.js config');
  }
  throw e;
}

When it happens

Trigger: Having cube.py in cwd while the installed @cubejs-backend/native is a fallback stub (installed on an unsupported platform or when compilation failed and npm fell back to the stub).

Common situations: npm installs on unsupported platforms silently picking the fallback package; Docker multi-arch builds pulling the wrong platform variant; native build failure during install going unnoticed until runtime.

Related errors

• Native extension is required to load Python configuration. $

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