cube-js/cube · error

Native extension is required to load Python configuration. $

Error message

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

What it means

When a cube.py file exists in the current working directory, Cube must load configuration through its Python bridge, which requires the cubejs-backend-native extension compiled for the current platform. isNativeSupported() returned a reason string indicating the native module cannot run here (unsupported architecture/OS or missing build), so Cube throws instead of silently failing.

Source

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

  protected createServer(config: CreateOptions, systemOptions?: SystemOptions): CubejsServer {
    return new CubejsServer(config, systemOptions);
  }

  public async lookupConfiguration(override: boolean = false): Promise<CreateOptions> {
    dotenv.config({
      override,
      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()

View on GitHub (pinned to 7d981676b3)

Solutions

1. Install/build cubejs-backend-native for your platform (ensure optionalDependencies are installed)
2. Switch to a supported base image (Debian/glibc instead of Alpine) or supported architecture
3. Remove/rename cube.py and configure the project in JavaScript (cube.js) instead
4. Check packages/cubejs-backend-native README for supported platforms and build from source if needed

Example fix

# before (Dockerfile)
FROM node:20-alpine

# after
FROM node:20-bookworm
# or delete cube.py and use cube.js configuration

const { isNativeSupported } = require('@cubejs-backend/native');
const supported = isNativeSupported();
if (fs.existsSync('cube.py') && supported !== true) {
  throw new Error(`cube.py present but native unsupported: ${supported.reason}`);
}

null

try {
  await server.listen();
} catch (e) {
  if (e.message.includes('Native extension is required to load Python configuration')) {
    console.error('Use a supported platform or convert cube.py to cube.js');
  }
  throw e;
}

When it happens

Trigger: Placing cube.py in the project root and starting the server on a platform where @cubejs-backend/native is not built/supported (e.g. unsupported arch like linux/arm64 without prebuilt binaries, Alpine/musl, or a fallback-only npm install).

Common situations: Deploying to ARM servers or Apple Silicon with no native binary; Alpine Docker images where glibc native modules don't load; npm skipping optional dependencies so the native package is absent; CI runners with unusual architectures.

Related errors

• Unable to load Python configuration because you are using th
• Native extension is required to process jinja files. ${NATIV

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