cube-js/cube · error

Databricks API error: ${res.statusText}

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.

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)

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' : 'Unexpe
• HTTP error! status: ${response.status}
• unexpected response ${response.statusText}
• HTTP ${response.status}: ${response.statusText}
• Failed to get access token: ${res.statusText}

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