Databricks returns an error when the service principal cannot access a required object or when the published data does not match the structure expected by segmentation. Review the error class and SQL state in Databricks query history, then use the matching resolution.

A successful Databricks connection test confirms OAuth authentication and SQL warehouse access. It does not confirm access to Unity Catalog objects.

Insufficient permissions

Error: INSUFFICIENT_PERMISSIONS (SQLSTATE 42501)

What this error means

The service principal cannot read or write a Databricks object required by the segment query.

Why the error occurs

One or more of these conditions apply:

• The service principal lacks USE CATALOG on a catalog or USE SCHEMA on a schema that the segment query uses.

• The service principal lacks SELECT on entities or a mapped interaction source.

• segment_results exists under another owner, and the service principal lacks MODIFY on the table.

• A mapped view owner lacks SELECT on an underlying table.

How to fix the issue

Correct the missing privilege or ownership configuration.

• Grant the missing privileges as described in Configure Databricks permissions for zero-copy segmentation.

• Confirm that the service principal owns segment_results or has SELECT and MODIFY on the table.

• For a mapped view, restore the view owner's access to every underlying table.

Preventive measures

Verify access after configuring permissions or changing interaction mappings.

• Run the verification steps after configuring permissions.

• Repeat the verification after adding or changing an interaction mapping.

• Keep ownership of segment_results with the service principal, or keep its SELECT and MODIFY grants in place.

Table or view not found

Error: TABLE_OR_VIEW_NOT_FOUND (SQLSTATE 42P01)

What this error means

The segment query cannot resolve an expected entity table, interaction table, or view.

Why the error occurs

One or more of these conditions apply:

• The connection's segmentationCatalog does not match databricksConfig.catalog for the deltalake adapter.

• Reltio Data Pipeline for Databricks has not created the target schema or entities.

• The data pipeline publishes a different table structure because storageFormat is not JSON or splitTable is true.

• The service principal lacks USE CATALOG on a catalog or USE SCHEMA on a schema, so Unity Catalog does not expose the object to that principal.

How to fix the issue

Confirm the schema name, published data, and privilege chain.

• Confirm that the connection's segmentationCatalog matches databricksConfig.catalog for the deltalake adapter.

• Confirm that the data pipeline completed successfully and published entities.

• Set storageFormat to JSON and splitTable to false, then configure and run the pipeline again.

• Grant USE CATALOG and USE SCHEMA to the service principal.

Preventive measures

Confirm the published objects before segment evaluation.

• Set segmentationCatalog to the data pipeline catalog when creating the Databricks connection.

• Confirm the published table structure before granting permissions.

• Run the permission verification queries before evaluating a segment.

Syntax error when granting warehouse access

Error: PARSE_SYNTAX_ERROR (SQLSTATE 42601)

What this error means

Databricks rejected a SQL GRANT command that attempted to assign access to the SQL warehouse.

Why the error occurs

A SQL warehouse is a workspace object, not a Unity Catalog securable object. Unity Catalog GRANT commands do not assign SQL warehouse permissions.

How to fix the issue

Assign warehouse access outside Unity Catalog.

• Assign CAN USE permission to the service principal through the SQL warehouse permissions page or the Databricks Permissions API.

Preventive measures

Use the correct access-control mechanism for each object type.

• Use SQL GRANT commands only for Unity Catalog objects.

• Use the warehouse permissions interface or Permissions API for SQL warehouse access.

Field not found

Error: FIELD_NOT_FOUND (SQLSTATE 42704)

What this error means

The segment query references a field that is not present in the published entity data.

Why the error occurs

The crosswalks structure in the published entities table does not contain a field required by the segmentation query.

How to fix the issue

Correct the published entity-data structure.

• Compare the published crosswalks structure with the fields required by the segment query.

• Correct the data pipeline export configuration.

• Run the data pipeline again, then reevaluate the segment.

Preventive measures

Validate the published data after pipeline changes.

• Validate the published entity-data schema after changing the data pipeline configuration.

• Evaluate a profile-only segment before introducing interaction-based rules.