What causes "API URL is empty" in cube-js/cube?

Pass the API URL explicitly: cube --api-url https://

API URL is empty

Error message

API URL is empty

What it means

cube-cli's Client::build validates the base API URL before constructing the HTTP client. If the URL is empty (after trimming trailing slashes), it returns the error 'API URL is empty' rather than making requests to a malformed endpoint.

Source

Thrown at rust/cube-cli/src/client.rs:250

/// recovery note that closes the same comment block is the only part that becomes LIVE,
/// since it is what a reader arrives at from the failure.
fn explains(value: &Value) -> Option<String> {
    if says_nothing(value) {
        return None;
    }

    match value {
        Value::String(said) => Some(said.to_string()),
        Value::Object(_) | Value::Array(_) => Some(value.to_string()),
        _ => None,
    }
}

impl Client {
    fn build(base_url: &str, token: &str, refresh: Option<RefreshAuth>) -> Result<Self> {
        let base_url = base_url.trim_end_matches('/').to_string();
        if base_url.is_empty() {
            bail!("API URL is empty");
        }
        Ok(Self {
            http: reqwest::Client::builder()
                .user_agent(concat!("cube-cli/", env!("CUBE_CLI_VERSION")))
                .build()?,
            base_url,
            token: Mutex::new(token.to_string()),
            refresh,
        })
    }

    pub fn new(base_url: &str, token: &str) -> Result<Self> {
        Self::build(base_url, token, None)
    }

    /// Construct a client that can auto-refresh its access token. When
    /// `context_name` is set, refreshed tokens are written back to that
    /// config context.

View on GitHub (pinned to 7d981676b3)

Solutions

Pass the API URL explicitly: cube <cmd> --api-url https://<cube-deployment>
Run `cube login --name <ctx>` to create a context with a valid URL and switch to it
Set the URL environment variable (e.g. CUBE_API_URL) in your shell/CI before running commands
Inspect the CLI config file and remove/fix contexts with empty url values

Example fix

// before
export CUBE_API_URL=""
cube data-model get
// after
export CUBE_API_URL="https://cube.example.com"
cube data-model get

Defensive patterns

Strategy: validation

Validate before calling

const url = process.env.CUBE_API_URL ?? '';
if (!url.trim()) { throw new Error('Set CUBE_API_URL or pass --api-url before running cube-cli'); }

Type guard

function hasApiUrl(cfg: { apiUrl?: string }): cfg is { apiUrl: string } {
  return typeof cfg.apiUrl === 'string' && cfg.apiUrl.trim().length > 0;
}

Try / catch

try {
  await runCliCommand();
} catch (e) {
  if (/API URL is empty/.test(String(e))) { console.error('Run `cube login --name <ctx>` or set --api-url'); process.exit(2); }
  throw e;
}

Prevention

Always run `cube login` before first use
Set the API URL env var in CI secrets, and assert it is non-empty in pipeline setup
Never set the URL variable to empty string to 'disable' it — unset it or fix it
Validate context configs contain non-empty url fields

When it happens

Trigger: Running any CLI command when no API URL has been configured: missing --api-url flag, empty CUBE_API_URL env var, or a context in the CLI config whose url field is empty.

Common situations: Fresh install without `cube login`; CI environments where the URL env var is unset or set to empty string; a corrupted/blank context entry in the CLI config file.

Related errors

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