Skip to main content
Connection failures usually cluster into a few causes: network path, credentials, TLS trust, or authorization on the source system. Work from the error string outward—confirm reachability, then identity, then permissions.

​
Common errors

Symptoms: JDBC or HTTP client hangs, then fails with read or connect timeout. Checks: Verify security groups, firewalls, private DNS from the runner (SaaS region IP or agent egress). Test with telnet/nc from the same network class. Increase driver timeouts only after the path is proven; long timeouts mask routing mistakes.
Copy the full error text and connection id from the UI when you open a support ticket; partial screenshots slow diagnosis.

​
Database-specific tips

Check pg_hba.conf for client IP and sslmode. Verify search_path if objects appear missing. For RDS/Aurora, confirm parameter groups allow your max connections and idle timeouts suit long jobs.
Confirm user@’%’ vs host-restricted grants. Caching SHA2 may require newer drivers or server RSA keys. Watch max_connections and wait_timeout for overnight ETL.
Validate SQL authentication vs Windows/AD integration when using gateways. Encrypt and trust flags must match what the instance enforces. Named instances need correct port or Browser access (often blocked—prefer static ports).
SERVICE_NAME vs SID mix-ups are common. Wallet paths and TNS aliases must exist on agents if you run JDBC locally. Check listener logs for TNS errors the thin client surfaces generically.
Replica set SRV URIs require DNS SRV resolution from the runner. SCRAM user must exist in the admin database for cluster admin tasks. TLS is mandatory on Atlas—match CA bundles.

​
Cloud storage permission issues

Object store errors often read 403, AccessDenied, or SignatureDoesNotMatch.
  • IAM role vs keys: Prefer short-lived role assumption; static keys leak in logs.
  • Bucket policy vs ACL: Modern buckets are policy-only; ACL mistakes show up as silent listing failures.
  • Prefix scope: Confirm the path your connection uses matches policy Resource ARNs.
  • KMS: Decrypt permission on the CMK is separate from S3 GetObject.
Use the cloud vendor’s policy simulator with the exact principal and resource ARN before you change production pipeline schedules.

​
SSH tunnel and agent connectivity

If you use SSH tunnels:
  • Failures on port 22 indicate bastion reachability or key issues before the database is involved.
  • When a pipeline agent opens the tunnel, allowlist the agent egress IP on the bastion.
  • Keepalive settings prevent NAT idle drops on long extracts.
Mixing VPN split tunneling with allowlists causes intermittent success—some sessions egress from corporate NAT, others from residential IPs.

Databases

Supported engines and connection fields.

Cloud storage

S3, Azure Blob, and GCS patterns.