cube-js/cube · error · Error

Native extension is required to process jinja files. ${NATIV

Error message

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

What it means

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.

Source

Thrown at packages/cubejs-schema-compiler/src/compiler/DataSchemaCompiler.ts:570

        }

        // Free unneeded resources
        this.compileV8ContextCache = null;
        this.cubeDictionary.free();
        this.cubeOnlySymbols.free();
        this.cubeAndViewSymbols.free();
        this.yamlCompiler.free();

        return res;
      });
    }

    return this.compilePromise;
  }

  private loadJinjaTemplates(files: FileContent[]): void {
    if (NATIVE_IS_SUPPORTED !== true) {
      throw new Error(
        `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'
      );
    }

    const jinjaEngine = this.yamlCompiler.getJinjaEngine();

    files.forEach((file) => {
      jinjaEngine.loadTemplate(file.fileName, file.content);
    });
  }

  /**
   * Macro files are hidden dependencies of any cube file that imports them —
   * minijinja resolves `{% import %}` lazily against its template store, so
   * the per-file Jinja render cache must be invalidated when *any* macro file
   * changes. Hashing all macro files together rather than tracking per-cube
   * imports keeps the implementation simple at the cost of over-invalidating

View on GitHub (pinned to 7d981676b3)

Solutions

1. Install/repair `@cubejs-backend/native` so the prebuilt binary loads (reinstall dependencies and check install logs).
2. Use a supported platform/architecture (Debian/Ubuntu based x64/arm64 images) for your deployment.
3. Remove or convert .jinja templates to plain SQL/YAML if native support cannot be enabled.
4. Read the linked README (packages/cubejs-backend-native#supported-architectures-and-platforms) for compatibility details.

Example fix

// Dockerfile before
FROM node:20-alpine
// after
FROM node:20-bookworm-slim
RUN yarn add @cubejs-backend/native

const { NATIVE_IS_SUPPORTED } = require('@cubejs-backend/native');
if (NATIVE_IS_SUPPORTED !== true && files.some(f => f.fileName.endsWith('.jinja'))) {
  throw new Error('Jinja templates require a supported platform with @cubejs-backend/native installed');
}

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; }

When it happens

Trigger: 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.

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

Related errors

• Unable to load @cubejs-backend/native, probably your system
• Please download and place databricks-jdbc-${OSS_DRIVER_VERSI
• Native extension is required to load Python configuration. $

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