Skip to Content
WarehousesTesting Connections

Testing Connections

Before a warehouse is saved or when troubleshooting an existing warehouse, Zeotap performs a connection test to verify that the warehouse is reachable, credentials are valid, and the required permissions are in place. This page explains how connection testing works, what is validated, and how to diagnose failures.

How Connection Testing Works

When you click Test Connection in the warehouse configuration form (or call the test API endpoint), Zeotap performs a series of validation steps:

Step 1: Network Connectivity

Zeotap attempts to establish a TCP connection to the warehouse host on the configured port. This step verifies:

  • The hostname or IP address resolves correctly via DNS
  • The port is open and accepting connections
  • No firewall, VPN, or security group rules are blocking the connection
  • SSL/TLS handshake succeeds (if required)

Step 2: Authentication

Using the provided credentials, Zeotap authenticates with the warehouse. Depending on the warehouse type, this may involve:

  • Username/Password — Standard credential validation (Snowflake)
  • Key Pair — RSA private key authentication (Snowflake)
  • Service Account JSON — Google Cloud IAM authentication (BigQuery)
  • Personal Access Token — Token-based authentication (Databricks)
  • Username/Password over HTTP headers — X-ClickHouse-User / X-ClickHouse-Key header authentication (ClickHouse)
  • Username/Password over a TLS database connection — Database user credentials (Redshift)

Step 3: Authorization

After authentication, Zeotap verifies that the authenticated user has access to the specified database, schema, or dataset:

  • Checks that the database/project exists
  • Confirms the user has USAGE or equivalent permissions on the target schema
  • For Snowflake, verifies the user can use the specified warehouse

Step 4: Query Execution

Zeotap executes a lightweight validation query — SELECT 1, or the engine’s equivalent — to confirm the connection is fully functional. It exercises the whole path in one statement: network, authentication, authorization, and query execution.

Step 5: Write Access to Operational Schemas

Zeotap creates and writes to six schemas (datasets/databases) in the connected warehouse at runtime: cdp_planner, cdp_audit, cdp_journey, cdp_identity, cdp_raw, and audit_logs. The connection test probes each one the same way the runtime does — create the schema if it does not exist, then create and drop a small _cdp_test table — so a missing grant surfaces during setup instead of on the first sync, journey, identity, loader, or observability run. A failed write step reports the exact GRANT/CREATE SCHEMA statements to run.

A seventh schema, cdp_prep, is probed only if Data Prep is enabled for the workspace (the write_prep step). Data Prep is a per-workspace entitlement, off by default; a workspace that does not have it never creates or reads that schema, so its connection test looks exactly as it did before the feature existed — no extra step, and no grant to ask for. Enabling the entitlement is therefore also the moment the test starts asking for it, which is deliberate: it is the one surface that tells a customer whether the grants they ran were the right ones. See the per-warehouse pages for the statements.

One more schema, cdp_metadata, is probed only if the metadata export is enabled for the workspace, and only on the source chosen to hold its table (the write_metadata step, after write_prep). The metadata export is a per-workspace entitlement, off by default: a workspace without it, and every other source in a workspace with it, sees no extra step.

Connection Test Results

Success

The form lists every step as it completes, each with a tick, and closes with All checks passed. once every step has. That confirms:

  • Network connectivity is established
  • Credentials are valid and accepted
  • The user has access to the specified database and schema
  • Queries can be executed against the warehouse
  • The operational schemas can be created and written to

A step can also pass with a warning — the check succeeded, but something about the result is worth knowing before you rely on it. The warning is shown beside the tick.

Failure

A failed test returns a red indicator with a specific error message. Common failure categories:

Error CategoryExample MessageRoot Cause
Network”Connection timed out”Firewall, security group, or DNS issue
Authentication”Authentication failed for user ‘X‘“Invalid credentials or disabled account
Authorization”Database ‘X’ does not exist or user lacks access”Missing permissions or wrong database name
Configuration”Invalid account identifier”Typo in account/host configuration
SSL/TLS”SSL certificate verification failed”Certificate mismatch or expired cert

Testing via the API

Both test endpoints stream their results with Server-Sent Events: one step event per test step as it finishes, then a final done event carrying the overall verdict. This is what lets the form tick each step off while the test is still running, rather than waiting for a single response at the end.

Test Before Saving

Test a configuration that has not been saved as a warehouse yet:

curl -N -X POST \
  https://agentic.zeotap.com/api/v1/workspaces/$WORKSPACE_ID/sources/test \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_type": "snowflake",
    "config": {
      "account": "myorg-my_account",
      "warehouse": "COMPUTE_WH",
      "database": "ANALYTICS",
      "schema": "PUBLIC",
      "auth_method": "password"
    },
    "credentials": {
      "username": "CDP_USER",
      "password": "your-password"
    }
  }'

To test as a credential that is already stored rather than one you paste, send warehouse_user_id instead of credentials. That is what the form does when you pick an existing warehouse user — a stored secret is never read back, so it could not otherwise be tested before saving.

Test a Saved Warehouse

Re-test a saved warehouse (useful after credential rotation). The verdict is recorded on the warehouse’s status:

curl -N -X POST \
  https://agentic.zeotap.com/api/v1/workspaces/$WORKSPACE_ID/sources/$SOURCE_ID/test \
  -H "Authorization: Bearer $API_TOKEN"

Response Format

Each step event carries one step’s outcome as it completes:

event: step
data: {"name":"authenticate","label":"Validate Snowflake credentials","status":"passed"}

event: step
data: {"name":"write_planner","label":"Verify permission to write to planner schema","status":"failed","error":"cannot create schema CDP_PLANNER: insufficient privileges","fix":"GRANT CREATE SCHEMA ON DATABASE ANALYTICS TO ROLE CDP_ROLE;"}

A step’s status is passed, failed or skipped. A failed step carries an error, and — where Zeotap can name the grant that would fix it — a fix holding the exact SQL to run.

The final done event carries the whole result:

event: done
data: {"success":false,"steps":[ ... every step, in order ... ]}

success is true only when no step failed.

Troubleshooting Connection Failures

Network / Timeout Issues

Symptoms: “Connection timed out” or “Could not resolve host”

Solutions:

  1. Verify the hostname/account identifier is correct
  2. Ensure Zeotap’s IP addresses are allowlisted in your warehouse’s network policy
  3. Check that the warehouse is running and not paused/suspended (common with Snowflake auto-suspend)
  4. For Databricks, confirm the cluster or SQL warehouse is running
  5. For ClickHouse, confirm the HTTP interface port is reachable and matches the protocol (8123 for HTTP, 8443 for HTTPS)
  6. For Redshift, confirm the cluster or workgroup is publicly accessible (or reachable via PrivateLink) and that its VPC security group allows inbound TCP on port 5439 from Zeotap’s egress IPs — Redshift is private by default, so this is a required setup step rather than optional hardening
  7. Verify DNS resolution from your network

Authentication Failures

Symptoms: “Authentication failed” or “Invalid credentials”

Solutions:

  1. Double-check the username and password (no trailing whitespace)
  2. For Snowflake key pair auth, ensure the private key is in PEM format and the public key is registered with the user
  3. For BigQuery, verify the service account JSON is complete and valid
  4. For Databricks, confirm the personal access token has not expired
  5. For ClickHouse, verify the username and password — they are sent as X-ClickHouse-User / X-ClickHouse-Key headers, and a Code: 516 error means the pair was rejected
  6. For Redshift, verify the database user and password — FATAL: password authentication failed for user "..." means the pair was rejected
  7. Check if the user account is locked or disabled in the warehouse

Authorization Errors

Symptoms: “Insufficient privileges” or “Database/Schema not found”

Solutions:

  1. Verify the database and schema names are spelled correctly (case-sensitive for some warehouses)
  2. Confirm the user has been granted the necessary roles:
    • Snowflake: USAGE on warehouse, database, and schema; SELECT on tables; CREATE SCHEMA on the database (or explicit write grants on the operational schemas)
    • BigQuery: bigquery.dataViewer role on the dataset; bigquery.jobUser and bigquery.dataEditor on the project (or WRITER on the pre-created operational datasets)
    • Databricks: USE CATALOG, USE SCHEMA, and SELECT permissions; CREATE SCHEMA on the catalog (or explicit write grants on the operational schemas)
    • ClickHouse: SELECT on the source database; CREATE DATABASE, CREATE TABLE, SELECT, INSERT, ALTER, and DROP TABLE on the cdp_planner, cdp_audit, cdp_journey, cdp_identity, cdp_raw, and audit_logs databases
    • Redshift: USAGE and SELECT on the source schema; CREATE ON DATABASE so the operational schemas can be created (or USAGE, CREATE on each pre-created cdp_planner, cdp_audit, cdp_journey, cdp_identity, cdp_raw, and audit_logs schema)
  3. If the failing step is write_prep, the workspace has Data Prep enabled and the same grants are needed on one more schema — cdp_prep on ClickHouse / Databricks / BigQuery / Redshift, CDP_PREP (unquoted, uppercase) on Snowflake. It is the only step in the list that is conditional, so a write_prep failure on a warehouse that has always passed its test means the entitlement was granted since it last ran, not that something regressed.
  4. If the failing step is write_metadata, the workspace has the metadata export enabled and the same grants are needed on cdp_metadata (CDP_METADATA, unquoted and uppercase, on Snowflake). It appears only on the source the export writes to, once the entitlement is granted.
  5. For Snowflake, ensure the user’s default role has the needed grants

SSL/TLS Issues

Symptoms: “SSL certificate verification failed” or “TLS handshake error”

Solutions:

  1. Ensure your warehouse supports TLS (most cloud warehouses require it)
  2. Verify the certificate has not expired
  3. Check that the hostname in the certificate matches the configured host

Health Checks

After a warehouse is created, Zeotap periodically runs automated health checks using the same connection test logic. If a health check fails:

  1. The warehouse status changes to Unhealthy
  2. Any syncs using models on that warehouse are marked with a warning
  3. A notification is sent to workspace administrators
  4. Zeotap continues to retry on subsequent health check intervals

To resolve an unhealthy warehouse, edit the warehouse configuration, update credentials if needed, and re-test the connection.

Next Steps

Last updated on
Creating a WarehouseCredentials