Troubleshooting AlloyDB connectivity
Symptom-first troubleshooting for AlloyDB for PostgreSQL connectivity - private IP errors, PSC handshake failures, IAM authentication issues, grants, large crawls, and sudden breakage.
Resolve common AlloyDB for PostgreSQL connectivity issues when integrating AlloyDB with Atlan. Find the symptom you're seeing in the quick index - each entry includes a check you can run yourself before opening a ticket.
Quick index
| You see | Most likely cause | Jump to |
|---|---|---|
app internal error: 500 on Test connection in Direct mode | Private IP entered as Host - unreachable from Atlan | Private IP in Direct |
| PSC endpoint built, but connection times out | Wrong service attachment URL, unaccepted endpoint, or DNS mis-mapping | PSC handshake |
| IAM auth fails; password auth works - or auth fails only behind a load balancer | IAM method/mode mismatch, or token signed for the wrong port | IAM authentication |
| Test connection passes, preflight or crawl fails on some schemas | Missing grants - not a network issue | Preflight and grants |
| Test passes, crawl runs 12–24 h or fails at the publish step | Very large instance - throughput, not connectivity | Large crawls |
| Worked for months, broke overnight, nothing changed on your side | Egress IP change or allowlist edit | Sudden breakage |
Test connection fails with "app internal error: 500" (Direct mode)
Symptom. First-time setup; Direct extraction selected; Host contains an address like 10.52.0.7 or 172.28.0.3; the test fails immediately with:
app internal error: 500
# or in logs: connection to server at "10.52.0.7", port 5432 failed:
# Connection timed out
Why. That's a private (RFC1918) address - only routable inside your own VPC. Atlan's SaaS cannot reach it over the internet, so the test fails at the network layer. Expected behavior, not a connector bug.
Fix. Either switch the extraction toggle to Self-Deployed Runtime (keeps the private IP as Host - the runtime reaches it locally, see the SDR guide), or set up PSC / a public IP with authorized networks and use the resulting hostname/public address as Host.
PSC endpoint exists but connections time out
Check in this order:
- Was the right URL shared? The value on your ticket must be a service attachment URL (
projects/…/regions/…/serviceAttachments/…), not the instance URI (projects/…/locations/…/clusters/…/instances/…). If the wrong one was shared, send the correct one on the same ticket. - Is the endpoint Accepted? In the Google Cloud console, open the service attachment's Connected endpoints. A Pending endpoint carries no traffic - accept it (or add Atlan's consumer project to the accept list, as named on your ticket). Nothing accepts itself.
- Is the hostname mapped to the right IP? If Accepted but still timing out, reply on the ticket: "please re-verify the DNS mapping for our hostname against the endpoint IP."
The mapped hostname resolves inside Atlan's network, not yours. Use Test connection in Atlan as the end-to-end check.
IAM authentication failures
Symptom. Password auth works but IAM fails; or errors like FATAL: PAM authentication failed for user …; or the IAM option you expected isn't in the UI.
- Wrong mode for the method. Workload Identity Federation appears only when Self-Deployed Runtime (on GKE) is selected - it's absent in Direct by design. See the auth matrix.
- IAM not enabled on the instance. IAM database authentication is an instance flag plus a database-level user. Confirm both with your Google Cloud admin, and that the IAM principal was granted
atlan_user_role. - Token expiry. IAM user tokens live about an hour - fine for a one-off test, guaranteed to break a schedule. Use an IAM service account for scheduled crawls.
- Port-rewriting hop. If traffic passes a load balancer/proxy listening on a non-default port, the IAM token gets signed for the wrong port and the database rejects it (PAM error). Use the advanced auth-port option or describe the topology on a ticket. Details in Special cases.
Preflight or per-schema crawl failures (network is fine)
Symptom. Test connection passes; preflight reports Check failed for $missingObjectName or Check failed. Missing some of the required grants…; or one schema's assets never appear.
Check yourself - does the crawl user actually have USAGE on each schema?
SELECT nspname AS schema_name,
has_schema_privilege('<atlan-user-or-iam-principal>', nspname, 'USAGE') AS can_usage
FROM pg_namespace
WHERE nspname NOT LIKE 'pg_%' AND nspname != 'information_schema';
Fix. Re-run the Phase 3 grants from the SDR guide for any schema showing f. For IAM auth, remember the database user name is the IAM principal (e.g. my-sa@my-project.iam), not a local username.
Crawl connects but runs forever or fails at publish
Symptom. Test connection and small crawls pass; a full crawl of a multi-million-asset instance runs 12–24 h, or fails in the publish step (asset creation), possibly slowing other workflows.
Why. This is a throughput/scale issue in metadata publishing, not a network problem - the extraction from AlloyDB already succeeded. Partition-heavy schemas (many time-partitioned tables) are the usual driver.
Fix. Scope with include/exclude filters and the table/view exclude regex; ask support to tune publish throughput for the initial load; keep the connector app/runtime image current. Do not rebuild your network path.
It worked for months, then broke overnight
- Ask support whether your tenant's egress IPs changed - tenant-specific values are announced to admins, and mails get missed.
- Ask your Google Cloud admin whether the authorized networks list or the instance's public IP setting was edited (Cloud Audit Logs show who and when).
- For PSC: confirm the endpoint still shows Accepted and the service attachment wasn't recreated (recreation changes its URL - a new attachment needs a new endpoint).
- For SDR: confirm the runtime is running and can still reach both your Atlan tenant URL (443) and the database (5432) - an egress-proxy change on your side is the usual culprit.
Opening ticket that gets solved fast
Include these six things - they usually turn a multi-day exchange into one reply:
- Your Atlan tenant URL and the failing workflow run link
- Connectivity method (Direct + public IP / PSC / self-deployed runtime) and the exact Host value configured
- How the instance is exposed: private IP only, public IP, or PSC (paste the service attachment URL if PSC)
- Auth method (password / IAM user / IAM service account / WIF) and, for IAM, the principal name
- The exact error text from the test or workflow logs
- Whether it ever worked, and if so when it stopped