Databricks
Troubleshooting
Common Databricks integration errors and fixes — authentication, discovery, harness, Mosaic AI, Genie, Vector Search, and Unity Catalog.
Common issues
| Issue | Fix |
|---|---|
401 Unauthorized | PAT is invalid or expired. Generate a new token. |
403 Forbidden | Insufficient privileges. Check UC grants and workspace permissions. For discovery, ensure BROWSE + USE CATALOG are granted. |
403 on api/2.1/unity-catalog/catalogs | Missing BROWSE or USE CATALOG on Unity Catalog. Grant both to the principal or user. |
invalid_client (OAuth) | Verify client ID and secret belong to an active service principal (M2M), or that the OAuth app is active (U2M). |
workspace not found | Ensure baseUrl matches your Databricks workspace URL exactly. |
fh not found | Install the Fabric Harness CLI and ensure fh is on your PATH. |
| Live run refuses to execute | Set the live gate: export FABRIC_DATABRICKS_TEST=1. Mock runs (--mock) never require it. |
| Source test fails | Check connectionError in config.json. Verify network and URL. |
| U2M browser does not open | Check that your system default browser is configured and that localhost is not blocked by a firewall. |
Mosaic AI 404 on serving endpoint | Verify the endpoint name and that the endpoint is in READY state. |
Mosaic AI 403 on serving endpoint | The PAT or service principal needs CAN QUERY on the serving endpoint. Grant in ML → Serving → Permissions. |
AI Gateway 429 rate limited | Increase the rate limit in the AI Gateway route, or add retry logic. |
| Genie MCP server not found | Ensure the Genie MCP binary path in args is correct. The npm package is not yet published — use a local binary. |
Genie 403 on space | The PAT needs CAN USE on the Genie space and the underlying SQL warehouse. |
| Vector Search index not found | Verify the index name and that it is in ACTIVE state. |
Vector Search 403 | The PAT needs CAN USE on the SQL warehouse linked to the Vector Search index. |
SQL Warehouse 400 warehouse not running | Use a Serverless warehouse (auto-starts), or start the Classic warehouse manually. |
| UC Browser returns empty results | Verify BROWSE + USE CATALOG grants. UC privileges are not transitive. |
UC Browser 403 on lineage | Lineage requires BROWSE on the table plus USE CATALOG / USE SCHEMA on parent objects. |
Deploy databricks: command not found | Live deploys shell out to the Databricks CLI. Install it and authenticate (databricks auth login). |
| Serving deploy endpoint returns errors | databricks-serving is a wrapper — the underlying agent must already be deployed and reachable (typically via databricks-app first). |
Related
- Authentication — PAT, M2M, and U2M setup
- Discovery & health — interpreting
source testresults - Harness bridge — mock/live gating and deploy targets
- Databricks REST API docs
- Unity Catalog API docs
- Databricks SQL Warehouse docs
Platform services
Extend the Databricks integration with Mosaic AI Model Serving, AI Gateway guardrails, Genie natural-language analytics, Vector Search RAG, SQL warehouses, and a read-only Unity Catalog browser.
Skills Configuration Guide
This guide explains how to create and configure skills in Fabric Agent.