Unity Catalog catalog not visible in one workspace despite grants: workspace bindings and isolation mode

#Symptom

Several workspaces (dev, test, prod) share one Unity Catalog metastore.

• In the prod workspace, SHOW CATALOGS lists prod. In dev, it doesn't, even for a metastore admin.
• Or the catalog is visible in dev, but writes fail with a read-only error.
• A query fails with an error that the catalog isn't accessible in the current workspace.

Grants look correct: SHOW GRANTS ON CATALOG prod lists the user's group.

#Why

Privileges (USE CATALOG, SELECT) say who can access a catalog. Workspace bindings say from which workspaces it can be accessed. Both must allow it.

A catalog has an isolation mode:

• OPEN: usable from every workspace attached to the metastore (subject to grants).
• ISOLATED: usable only from workspaces it is bound to.

Each binding is either read-write or read-only. Storage credentials and external locations can be bound the same way. The workspace catalog that Databricks creates automatically for a new workspace is bound to that workspace by default.

#Step 1: check the catalog's isolation mode

databricks catalogs get prod --output json | jq '{name, isolation_mode, owner}'

#Step 2: list the bindings

databricks workspace-bindings get-bindings catalog prod --output json

You'll see entries like:

{ "workspace_id": 1234567890123456, "binding_type": "BINDING_TYPE_READ_WRITE" }

Find the workspace ID of the workspace you're in: it's the number in the workspace URL (adb-<workspace-id>.<n>.azuredatabricks.net).

#Step 3: add or change the binding (if this access is intended)

databricks workspace-bindings update-bindings catalog prod --json '{
  "add": [ { "workspace_id": 2222222222222222, "binding_type": "BINDING_TYPE_READ_ONLY" } ]
}'

Read-only binding is a good pattern for giving dev or analytics workspaces safe access to production data.

Warning

Isolation is often deliberate: production catalogs bound only to production workspaces. Check with the data platform owner before adding a binding. Binding prod read-write to a dev workspace defeats the environment separation.

To make a catalog bindable in the first place, set it to isolated (owner or metastore admin):

databricks catalogs update prod --isolation-mode ISOLATED

When you switch to ISOLATED, the workspace you run it from is bound automatically; check other workspaces don't lose access unexpectedly.

#Step 4: check storage credentials and external locations

A catalog may be visible, but reading external tables or volumes fails because the external location or storage credential behind them is bound to other workspaces only:

databricks workspace-bindings get-bindings external_location ext_raw_landing --output json
databricks workspace-bindings get-bindings storage_credential sc_lake_prod --output json

The securable type names in the CLI and API can differ slightly between versions (external_location vs external-locations); check databricks workspace-bindings get-bindings --help.

#Other causes that look the same

#Prevent it next time

• Manage bindings in Terraform (databricks_workspace_binding) alongside catalog grants, so access is reviewed in one place.
• Document the environment model: which catalogs are bound to which workspaces, and with what binding type.
• Related: Unity Catalog location overlap errors.