cube-js/cube · critical

CUBESQL_CUBE_TOKEN is a required ENV variable

Error message

CUBESQL_CUBE_TOKEN is a required ENV variable

What it means

The HTTP-based authentication service builds an HttpAuthContext whose access_token comes from the CUBESQL_CUBE_TOKEN environment variable. If that variable is unset, the code panics because CubeSQL cannot authenticate against the Cube deployment without an API token.

Source

Thrown at rust/cubesql/cubesql/src/sql/auth_service.rs:80

#[derive(Debug)]
pub struct SqlAuthDefaultImpl;

crate::di_service!(SqlAuthDefaultImpl, [SqlAuthService]);

#[async_trait]
impl SqlAuthService for SqlAuthDefaultImpl {
    async fn authenticate(
        &self,
        _request: SqlAuthServiceAuthenticateRequest,
        _user: Option<String>,
        password: Option<String>,
    ) -> Result<AuthenticateResponse, CubeError> {
        Ok(AuthenticateResponse {
            context: Arc::new(HttpAuthContext {
                access_token: env::var("CUBESQL_CUBE_TOKEN")
                    .ok()
                    .unwrap_or_else(|| panic!("CUBESQL_CUBE_TOKEN is a required ENV variable")),
                base_path: env::var("CUBESQL_CUBE_URL")
                    .ok()
                    .unwrap_or_else(|| panic!("CUBESQL_CUBE_URL is a required ENV variable")),
            }),
            password,
            skip_password_check: false,
        })
    }
}

View on GitHub (pinned to 7d981676b3)

Solutions

1. Set CUBESQL_CUBE_TOKEN to the Cube deployment's API token before starting the process
2. Add the variable to your container spec / .env file and restart
3. Verify with a shell into the container that `echo $CUBESQL_CUBE_TOKEN` is non-empty

Example fix

// before
 cargo run -p cubesql
// after
 CUBESQL_CUBE_TOKEN=<api-token> CUBESQL_CUBE_URL=http://cube:4000 cargo run -p cubesql

// startup preflight before launching cubesql
fn require_env(key: &str) -> Result<String, String> {
    match std::env::var(key) {
        Ok(v) if !v.is_empty() => Ok(v),
        _ => Err(format!("{} is required", key)),
    }
}
let _ = require_env("CUBESQL_CUBE_TOKEN")?;

When it happens

Trigger: Running the CubeSQL standalone/meta-transport binary with the HTTP auth service without exporting CUBESQL_CUBE_TOKEN before startup.

Common situations: Kubernetes/Docker manifests missing the env entry; .env file not loaded; renaming variables during a config refactor; running the binary manually from a shell without the deployment's env.

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

• CUBESQL_CUBE_URL is a required ENV variable
• wrong configuration for environment variable '{}' with '{}'
• wrong configuration for environment variable '{}' with '{}'
• This query doesnt have a plan, because it already has values
• Should be rewritten with UtcTimestamp function

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