Symptoms
- Dashboards and Power BI reports time out; warehouse stuck
STARTINGor flipping between states. - Query history shows many queries
QUEUEDfor minutes.
1. Warehouse state and type
databricks warehouses get <warehouse-id> --output json | \
jq '{name, state, warehouse_type, enable_serverless_compute, cluster_size, min_num_clusters, max_num_clusters, auto_stop_mins, health}'
| Type | Start failures usually come from |
|---|---|
| Serverless | Rare; check Databricks status page / workspace serverless availability and network policies |
| Pro / Classic | Your subscription: VM quota, capacity stockouts, VNet/subnet IPs, NSG/firewall changes |
For pro/classic, the health field and warehouse events show the cloud error (quota or launch failures). See the quota and subnet runbooks for fixes; switching a critical BI warehouse to serverless is often the fastest workaround.
2. Queued queries: capacity or a few heavy queries?
SELECT statement_id, executed_by, execution_status, total_duration_ms/1000 AS secs,
waiting_at_capacity_duration_ms/1000 AS queued_s, read_bytes/1e9 AS gb_read, left(statement_text, 80) AS sql
FROM system.query.history
WHERE compute.warehouse_id = '<warehouse-id>' AND start_time > now() - INTERVAL 1 HOUR
ORDER BY total_duration_ms DESC LIMIT 20;
| Finding | Fix |
|---|---|
| Many short queries queued, clusters at max | Raise max_num_clusters (scaling) |
| A few huge queries hogging it | Cancel them; move ad-hoc/ETL to another warehouse |
| Power BI refresh at the top of the hour | Stagger refreshes, use a separate warehouse for refresh vs. interactive |
databricks warehouses edit <warehouse-id> --max-num-clusters 6
Cancel a runaway query from Query history (or the statement execution API for API-submitted statements).
3. Power BI connection storms
Import-mode refreshes of many models in parallel, or DirectQuery reports with dozens of visuals, can flood a warehouse.
- Limit DirectQuery concurrency per data source in the semantic model settings.
- Use aggregations/import for heavy visuals; DirectQuery only where freshness requires it.
- Separate warehouses:
wh-bi-interactive(serverless, scales out) andwh-bi-refresh.
4. Permissions-looking failures
If the warehouse runs but users get errors, check CAN USE permission on the warehouse and Unity Catalog grants — and that the Power BI gateway or service uses a valid credential (OAuth token or service principal).
5. Auto-stop surprises
A warehouse with a short auto-stop restarts on the first query; classic/pro warehouses take minutes to start, which looks like an outage to users at 08:00. Serverless starts in seconds. For pro/classic, schedule a warm-up query before business hours or increase auto-stop.
Tip
Put a query timeout on BI warehouses (
STATEMENT_TIMEOUTworkspace or warehouse config) so a single bad report query can't run for hours.
Prevent it next time
- Serverless for interactive BI where available.
- Separate warehouses by workload; scaling limits sized from query history peaks.
- Alerts on queued time (from
system.query.history) and warehouse start failures.