{"record":{"id":"da9b3689c33d84c4","repo":"cube-js/cube","slug":"native-extension-is-required-to-process-jinja-file","errorCode":null,"errorMessage":"Native extension is required to process jinja files. ${NATIVE_IS_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 process jinja files\\. (.+?)\\. Read more: https://github\\.com/cube-js/cube/blob/master/packages/cubejs-backend-native/README\\.md#supported-architectures-and-platforms","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cubejs-schema-compiler/src/compiler/DataSchemaCompiler.ts","lineNumber":570,"sourceCode":"        }\n\n        // Free unneeded resources\n        this.compileV8ContextCache = null;\n        this.cubeDictionary.free();\n        this.cubeOnlySymbols.free();\n        this.cubeAndViewSymbols.free();\n        this.yamlCompiler.free();\n\n        return res;\n      });\n    }\n\n    return this.compilePromise;\n  }\n\n  private loadJinjaTemplates(files: FileContent[]): void {\n    if (NATIVE_IS_SUPPORTED !== true) {\n      throw new Error(\n        `Native extension is required to process jinja files. ${NATIVE_IS_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    const jinjaEngine = this.yamlCompiler.getJinjaEngine();\n\n    files.forEach((file) => {\n      jinjaEngine.loadTemplate(file.fileName, file.content);\n    });\n  }\n\n  /**\n   * Macro files are hidden dependencies of any cube file that imports them —\n   * minijinja resolves `{% import %}` lazily against its template store, so\n   * the per-file Jinja render cache must be invalidated when *any* macro file\n   * changes. Hashing all macro files together rather than tracking per-cube\n   * imports keeps the implementation simple at the cost of over-invalidating","sourceCodeStart":552,"sourceCodeEnd":588,"githubUrl":"https://github.com/cube-js/cube/blob/7d981676b36392fec34088b9afab6bdcad40207c/packages/cubejs-schema-compiler/src/compiler/DataSchemaCompiler.ts#L552-L588","documentation":"Jinja (.jinja) template support in data models requires the cubejs-backend-native extension, which is only available on supported architectures/platforms. loadJinjaTemplates throws this Error when jinja files are present but the native module is missing or unsupported, including a reason string from NATIVE_IS_SUPPORTED.","triggerScenarios":"A project includes *.jinja files in the schema folder, but the deployment runs on an unsupported platform/architecture (e.g. Alpine on unsupported glibc arch, ARM without prebuilt binaries) or the native package failed to install, so NATIVE_IS_SUPPORTED !== true.","commonSituations":"Docker images based on Alpine or exotic architectures; installing with npm/yarn optional-dependency failures silently skipping the native module; serverless environments with incompatible runtimes; upgrading Node versions without a matching native binary.","solutions":["Install/repair `@cubejs-backend/native` so the prebuilt binary loads (reinstall dependencies and check install logs).","Use a supported platform/architecture (Debian/Ubuntu based x64/arm64 images) for your deployment.","Remove or convert .jinja templates to plain SQL/YAML if native support cannot be enabled.","Read the linked README (packages/cubejs-backend-native#supported-architectures-and-platforms) for compatibility details."],"exampleFix":"// Dockerfile before\nFROM node:20-alpine\n// after\nFROM node:20-bookworm-slim\nRUN yarn add @cubejs-backend/native","handlingStrategy":"fallback","validationCode":"const { NATIVE_IS_SUPPORTED } = require('@cubejs-backend/native');\nif (NATIVE_IS_SUPPORTED !== true && files.some(f => f.fileName.endsWith('.jinja'))) {\n  throw new Error('Jinja templates require a supported platform with @cubejs-backend/native installed');\n}","typeGuard":null,"tryCatchPattern":"try { await compiler.compile(); } catch (e) { if (/Native extension is required/.test(e.message)) { console.error('Unsupported platform or missing @cubejs-backend/native:', e.message); } throw e; }","preventionTips":["Deploy on supported x64/arm64 Debian/Ubuntu-based images","Verify optional native dependency installation logs","Avoid .jinja templates unless native support is guaranteed in all environments"],"tags":["native-module","jinja","platform-support","installation"],"backgroundTag":"missing-native-extension","analyzedSha":"7d981676b36392fec34088b9afab6bdcad40207c","analyzedAt":"2026-09-02T03:45:10.400Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}