Troubleshooting Connectivity

1. Connectivity Issues (Host / Port)

Wrong Port

Generic Error: status: 504; status text: ; body: "\r\n504 Gateway Time-out\r\n\r\n504 Gateway Time-out\r\nnginx\r\n\r\n\r\n a padding to disable MSIE and Chrome friendly error page \r\n a padding to disable MSIE and Chrome friendly error page \r\n a padding to disable MSIE and Chrome friendly error page \r\n a padding to disable MSIE and Chrome friendly error page \r\n a padding to disable MSIE and Chrome friendly error page \r\n a padding to disable MSIE and Chrome friendly error page \r\n"

Wrong Host

java.net.UnknownHostException: dbc-72dd4058-dcc9.cloud.databricks.

Cause

Incorrect host URL
Incorrect or blocked port
Network/firewall restrictions
Malformed Databricks workspace URL

How to Fix

Step 1: Verify the host

Ensure the host follows the correct format:

https://<databricks-instance>.cloud.databricks.com

Step 2: Verify the port

Default port: 443
Ensure outbound access to:

*.cloud.databricks.com:443

Step 3: Check the network

Ensure your firewall allows outbound HTTPS traffic
If you use private networking, verify your virtual private cloud (VPC) or proxy settings

2. Authentication Issues (Service Principal / PAT)

Error Message

Invalid credentials type provided. Please ensure the credentials start with "dapi".

Credentials are invalid or not in correct format

Unauthorized access to Org

Cause

Incorrect credential type (personal access token (PAT) vs. service principal)
Invalid or malformed token
Service principal not active
Token generated incorrectly

How to Fix

Step 1: Validate the credential type

PATs must start with:

dapi

Step 2: Check the service principal setup

If you use a service principal:

Ensure it is active
Ensure it is added to the workspace
Ensure it has required permissions

Step 3: Regenerate credentials

Recreate the PAT or service principal
Ensure correct format (no extra spaces)

3. PAT Scope Issues

Error Message

Provided PAT token does not have required scopes: sql

Cause

The PAT does not have the required permissions to access SQL warehouses.

How to Fix

Go to Databricks > User Settings
Generate a new PAT
Ensure it includes SQL access scope

4. Warehouse / SQL Endpoint Issues

Error Message

Failed to check if warehouse can be used

Cause

Warehouse does not exist
Service principal/user does not have access
Warehouse is stopped

How to Fix

Verify the warehouse exists.
Grant the Can Use permission on the SQL warehouse.
Ensure the warehouse is running.

5. Catalog & Schema Permission Issues

Error Messages

Failed to check catalog permission: USE on DATABASE samples

Failed to check catalog permission: USE on SCHEMA samples.information_schema

Failed to check catalog permission: SELECT on TABLE samples.information_schema.column_tags

Cause

Missing basic access to:

Catalog (database)
Schema
Tables

How to Fix

Grant required permissions:

GRANT USE CATALOG ON CATALOG <catalog_name> TO `<Application_ID>`;
GRANT USE SCHEMA ON SCHEMA <catalog_name>.<schema_name> TO `<Application_ID>`;
GRANT SELECT ON TABLE <catalog_name>.<schema_name>.<table_name> TO `<Application_ID>`;

6. Lineage Permission Issues

Error Messages

Failed to check lineage permission: SELECT on TABLE system.access.column_lineage

Failed to check lineage permission: USE on SCHEMA system.access

Failed to check lineage permission: SELECT on TABLE samples.information_schema.columns

Cause

Sifflet cannot access lineage-related system tables.

Missing access to:

system.access schema
Lineage tables
Metadata schemas

How to Fix

Grant permissions:

GRANT USE SCHEMA ON SCHEMA system.access TO `<Application_ID>`;
GRANT SELECT ON TABLE system.access.column_lineage TO `<Application_ID>`;

Also ensure:

GRANT USE CATALOG ON CATALOG system TO `<Application_ID>`;

7. Missing Optional Permissions (Warnings)

Warning Message

Missing SELECT permission on system.lakeflow.pipeline_update_timeline

Cause

Missing access to pipeline metadata.

This impacts:

Linking Databricks jobs to tables
Pipeline observability

How to Fix (Optional)

GRANT SELECT ON TABLE system.lakeflow.pipeline_update_timeline TO `<Application_ID>`;