Check Server Hostname (no https://) and HTTP Path; make sure the SQL warehouse exists and you can use it. A stopped serverless warehouse starts automatically, so wait a few seconds and try again
Authentication error with a token
The token may be expired or revoked. Generate a new one and save the connection again
Sign in doesn't open a browser
QGIS needs a desktop session (it won't work over a headless remote session). Check nothing else is using local port 8020, which receives the sign-in
"use_kernel=True requires the optional databricks-sql-kernel extension", or a Real-Time connection shows "Install the Databricks SQL kernel" in the Browser panel
The warehouse is a Lakehouse Real-Time warehouse. Click Yes when the plugin offers to install the kernel (or double-click the Browser item), then try again; no restart is needed. To install by hand: pip install --user "databricks-sql-kernel>=1.1.0,<2.0.0" with the same Python as QGIS (3.10 or later)
Signed in but later connections fail
Delete databricks_oauth_tokens.json from your profile folder (Settings → User Profiles → Open Active Profile Folder) and click Sign in again
You need SELECT permission and a GEOMETRY/GEOGRAPHY column. For lat/long tables, use a custom query with ST_POINT
A saved-in-project layer shows in Handle Unavailable Layers when the project opens
Its saved connection isn't on this computer. Create a connection with the same name (see Share a project), then reopen the project
"Save this connection first…"
Personal-access-token connections must be saved before Save in project. Click Save Connection in the main dialog
"Only a single SELECT … can be saved as a layer"
Save in project accepts one SELECT or WITH … SELECT statement
Saved layer draws nothing
Zoom to it (right-click → Zoom to Layer(s)). Check the query returns a geometry column, and that the coordinates match the coordinate system (e.g. ST_POINT(longitude, latitude, 4326); longitude first)
Layer is slow when zoomed right out
It's fetching every feature in view. Zoom in, filter in your SQL, or aggregate (e.g. H3 cells)