Warehouse is unhealthy: ${data.health?.summary}. Details: ${

Error message

Warehouse is unhealthy: ${data.health?.summary}. Details: ${data.health?.details}

What it means

testConnection rejects the connection test when the warehouse reports health.status === 'FAILED' with a summary and details from Databricks. DEGRADED is deliberately tolerated, so this error means Databricks itself says the warehouse is fully failing health checks.

Source

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

    }

    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[],
    _options: any,
  ) {
    if (this.config.catalog) {
      const [schema] = preAggregationTableName.split('.');
      return super.loadPreAggregationIntoTable(
        preAggregationTableName,
        loadSql.replace(
          new RegExp(`(?<=\\s)${schema}\\.(?=[^\\s]+)`, 'g'),
          `${this.config.catalog}.${schema}.`
        ),
        params,

View on GitHub (pinned to 7d981676b3)

Solutions

Read data.health.summary/details (reproduced in the error message) and fix the underlying warehouse issue in the Databricks UI
Reduce warehouse size / min-clusters or switch to serverless to avoid capacity limits
Check the Databricks workspace for failed cluster start logs (instance profile, subnet, storage credentials)
Retry later if the cause is regional capacity unavailability

Example fix

// before
// e.g. health FAILED due to capacity
// warehouse size: 4X-Large, min_clusters: 4
// after
// smaller, serverless warehouse config in Databricks UI
// type: serverless, size: Medium

Defensive patterns

Strategy: try-catch

Validate before calling

const data = await (await fetch(`https://${host}/api/2.0/sql/warehouses/${warehouseId}`, { headers: { Authorization: `Bearer ${token}` } })).json();
if (data.health?.status === 'FAILED') throw new Error(`Warehouse unhealthy: ${data.health?.summary}`);

Try / catch

try {
  await driver.testConnection();
} catch (e) {
  if (e.message.startsWith('Warehouse is unhealthy')) {
    // read summary/details, page the platform team; health may recover so a delayed retry is reasonable
  }
  throw e;
}

Prevention

Monitor warehouse health via Databricks system tables/alerts
Size warehouses within cloud capacity limits; prefer serverless where available
Check instance profiles/subnets/storage credentials on warehouse creation

When it happens

Trigger: testConnection inspects data.health?.status from the warehouse describe API and it is exactly 'FAILED'.

Common situations: Warehouse failing to start (cloud instance capacity, IAM/instance-profile problems, storage access misconfiguration); oversized min-cluster config; regional capacity issues on AWS/Azure.

Related errors

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