cube-js/cube · error

Databricks API error

Error message

Databricks API error: ${res.statusText}

What it means

Thrown by testConnection when the Databricks REST call to describe the SQL warehouse (GET /api/2.0/sql/warehouses/{id}) returns a non-OK status. This API check runs before the JDBC connection test so configuration problems surface early. The statusText is included but not the response body or status code.

Solutions

1. Check that the JDBC URL httpPath points at a real SQL warehouse (/sql/1.0/warehouses/<id>) and the extracted warehouseId is correct
2. Verify the OAuth token/service principal has permission to query that warehouse
3. Retry if status was 429/503 (transient throttling), and check Databricks workspace status
4. Call the API manually with curl using the same token to see the full error body

Example fix

// before
throw new Error(`Databricks API error: ${res.statusText}`);
// after
if (!res.ok) {
  const body = await res.text();
  throw new Error(`Databricks API error: ${res.status} ${res.statusText}: ${body}`);
}

const res = await fetch(`https://${host}/api/2.0/sql/warehouses/${warehouseId}`, { headers: { Authorization: `Bearer ${token}` } });
if (!res.ok) console.error('Warehouse API check failed:', res.status, await res.text());

try {
  await driver.testConnection();
} catch (e) {
  if (String(e.message).startsWith('Databricks API error')) {
    // inspect res.status cause (401/403/404/429), back off and retry for 429/5xx
  }
  throw e;
}

When it happens

Trigger: testConnection fetches the warehouse info endpoint with an Authorization Bearer token; Databricks returns 401/403/404/429/5xx so res.ok is false.

Common situations: Wrong warehouseId parsed from the JDBC httpPath; token lacking CAN_USE/MANAGE permission on the warehouse; expired access token; transient 429 rate limiting or 503 from Databricks.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

• ${response.status === 401 ? 'Unauthorized request' …
• Can't fetch metrics from Dbt Cloud
• Failed to get access token
• HTTP error! status
• HTTP

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

Appendix: source

Thrown at packages/cubejs-databricks-jdbc-driver/src/DatabricksDriver.ts:398

  public override async testConnection() {
    let token: string;

    // Databricks docs on accessing REST API
    // https://docs.databricks.com/aws/en/dev-tools/auth/oauth-m2m
    if (this.config.properties.OAuth2Secret) {
      const at = await this.getValidAccessToken();
      token = `Bearer ${at}`;
    } else {
      token = `Bearer ${this.config.properties.PWD}`;
    }

    const res = await fetch(`https://${this.parsedConnectionProperties.host}/api/2.0/sql/warehouses/${this.parsedConnectionProperties.warehouseId}`, {
      headers: { Authorization: token },
    });

    if (!res.ok) {
      throw new Error(`Databricks API error: ${res.statusText}`);
    }

    const data = await res.json();

    if (['DELETING', 'DELETED'].includes(data.state)) {
      throw new Error(`Warehouse is being deleted (current state: ${data.state})`);
    }

    // There is also DEGRADED status, but it doesn't mean that cluster is 100% not working...
    if (data.health?.status === 'FAILED') {
      throw new Error(`Warehouse is unhealthy: ${data.health?.summary}. Details: ${data.health?.details}`);
    }
  }

  public override async loadPreAggregationIntoTable(
    preAggregationTableName: string,
    loadSql: string,
    params: unknown[],

View on GitHub (pinned to 7d981676b3)