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

Verify Host

Ensure the host follows the correct format:

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

Verify Port

Default port: 443
Ensure outbound access to:

*.cloud.databricks.com:443

Network Checks

Ensure firewall allows outbound HTTPS traffic
If using private networking, verify VPC / 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 (PAT vs Service Principal)
Invalid or malformed token
Service principal not active
Token generated incorrectly

How to Fix

Validate Credential Type

PAT tokens must start with:

dapi

Service Principal Setup

If using a Service Principal:

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

Regenerate Credentials

Recreate PAT token or Service Principal
Ensure correct format (no extra spaces)

3. PAT Token Scope Issues

Error Message

Provided PAT token does not have required scopes: sql

Cause

The Personal Access Token (PAT) does not have required permissions to access SQL warehouses.

How to Fix

Go to Databricks → User Settings
Generate a new PAT token
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 warehouse exists
Grant access:

Can Use permission on SQL warehouse
1. Ensure 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>;