cube-js/cube · error · minijinja::Error

unknown env variable {}

Error message

unknown env variable {}

What it means

The native backend's MiniJinja `env` function resolves environment variables for templates. When the requested variable is not set and no default was provided, it raises `unknown env variable {var_name}` as an `InvalidOperation` error. Unlike Python's `os.environ[...]`, there is no lenient mode unless the template supplies a default via the function's arguments.

Source

Thrown at packages/cubejs-backend-native/src/template/entry.rs:45

        let debug_info = options
            .get_value(cx, "debugInfo")?
            .downcast_or_throw::<JsBoolean, _>(cx)?
            .value(cx);

        let mut engine = mj::Environment::new();
        engine.set_debug(debug_info);
        engine.add_function(
            "env_var",
            |var_name: String, var_default: Option<String>, _state: &minijinja::State| {
                if let Ok(value) = std::env::var(&var_name) {
                    return Ok(mj::value::Value::from(value));
                }

                if let Some(var_default) = var_default {
                    return Ok(mj::value::Value::from(var_default));
                }

                let err = minijinja::Error::new(
                    mj::ErrorKind::InvalidOperation,
                    format!("unknown env variable {}", var_name),
                );

                Err(err)
            },
        );
        engine.set_auto_escape_callback(|_name: &str| mj::AutoEscape::Json);

        #[cfg(feature = "python")]
        engine_python::mj_inject_python_extension(cx, options, &mut engine)?;

        let workers_count = {
            let workers_count_float = options
                .get_value(cx, "workers")?
                .downcast_or_throw::<JsNumber, _>(cx)?
                .value(cx);

View on GitHub (pinned to 7d981676b3)

Solutions

1. Export/set the missing environment variable before starting the Cube process.
2. Add a default in the template: `env('VAR', 'default')`.
3. Fix the variable name typo in the data model.
4. Ensure your deployment (Docker/K8s) passes the variable into the container.

Example fix

// before
{{ env('CUBE_API_SECRET') }}
// after
{{ env('CUBE_API_SECRET', 'dev-secret') }}

// in shell, before starting Cube:
[ -n "$CUBE_API_SECRET" ] || { echo "CUBE_API_SECRET is not set"; exit 1; }

When it happens

Trigger: A data model/template calls `env('SOME_VAR')` where `SOME_VAR` is not present in the process environment and the call supplies no `var_default` argument.

Common situations: Deploying to a new environment where required env vars weren't configured, typos in variable names, secrets defined in one environment (CI) but not another (local dev), container missing `-e` flags.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• CUBEJS_DB_NAME can`t be empty.
• Please specify CUBEJS_DB_URL
• Error while calling filter: {}
• Converting from {:?} to Python is not supported
• Unable to convert Seq to Python

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