{"record":{"id":"e14a2353fe465939","repo":"cube-js/cube","slug":"native-extension-is-required-to-load-python-config","errorCode":null,"errorMessage":"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","messagePattern":"Native extension is required to load Python configuration\\. (.+?)\\. Read more: https://github\\.com/cube-js/cube/blob/master/packages/cubejs-backend-native/README\\.md#supported-architectures-and-platforms","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/cubejs-server/src/server/container.ts","lineNumber":273,"sourceCode":"  protected createServer(config: CreateOptions, systemOptions?: SystemOptions): CubejsServer {\n    return new CubejsServer(config, systemOptions);\n  }\n\n  public async lookupConfiguration(override: boolean = false): Promise<CreateOptions> {\n    dotenv.config({\n      override,\n      multiline: 'line-breaks'\n    });\n\n    const devMode = getEnv('devMode');\n    if (devMode) {\n      process.env.NODE_ENV = 'development';\n    }\n\n    if (fs.existsSync(path.join(process.cwd(), 'cube.py'))) {\n      const supported = isNativeSupported();\n      if (supported !== true) {\n        throw new Error(\n          `Native extension is required to load Python configuration. ${supported.reason}. Read more: ` +\n          'https://github.com/cube-js/cube/blob/master/packages/cubejs-backend-native/README.md#supported-architectures-and-platforms'\n        );\n      }\n\n      if (isFallbackBuild()) {\n        throw new Error(\n          'Unable to load Python configuration because you are using the fallback build of native extension. Read more: ' +\n          'https://github.com/cube-js/cube/blob/master/packages/cubejs-backend-native/README.md#supported-architectures-and-platforms'\n        );\n      }\n\n      return this.loadConfigurationFromPythonFile();\n    }\n\n    if (fs.existsSync(path.join(process.cwd(), 'cube.ts'))) {\n      return this.loadConfigurationFromMemory(\n        this.getTypeScriptCompiler().compileConfiguration()","sourceCodeStart":255,"sourceCodeEnd":291,"githubUrl":"https://github.com/cube-js/cube/blob/7d981676b36392fec34088b9afab6bdcad40207c/packages/cubejs-server/src/server/container.ts#L255-L291","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Install/build cubejs-backend-native for your platform (ensure optionalDependencies are installed)","Switch to a supported base image (Debian/glibc instead of Alpine) or supported architecture","Remove/rename cube.py and configure the project in JavaScript (cube.js) instead","Check packages/cubejs-backend-native README for supported platforms and build from source if needed"],"exampleFix":"# before (Dockerfile)\nFROM node:20-alpine\n\n# after\nFROM node:20-bookworm\n# or delete cube.py and use cube.js configuration","handlingStrategy":"validation","validationCode":"const { isNativeSupported } = require('@cubejs-backend/native');\nconst supported = isNativeSupported();\nif (fs.existsSync('cube.py') && supported !== true) {\n  throw new Error(`cube.py present but native unsupported: ${supported.reason}`);\n}","typeGuard":"null","tryCatchPattern":"try {\n  await server.listen();\n} catch (e) {\n  if (e.message.includes('Native extension is required to load Python configuration')) {\n    console.error('Use a supported platform or convert cube.py to cube.js');\n  }\n  throw e;\n}","preventionTips":["Check cubejs-backend-native README for supported architectures before deploying","Keep configuration in cube.js unless you control the deployment platform","Avoid Alpine/musl images when using the native extension","Ensure optionalDependencies are not skipped (no --no-optional installs)"],"tags":["native-extension","python-config","platform-support"],"backgroundTag":"native-module-unsupported-platform","analyzedSha":"7d981676b36392fec34088b9afab6bdcad40207c","analyzedAt":"2026-09-02T03:45:10.400Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}