Troubleshooting Cloud SQL for PostgreSQL connectivity
Symptom-first troubleshooting for Cloud SQL for PostgreSQL connectivity - private IP errors, timeouts dressed as auth failures, SSL mismatches, IAM login, agent hangs, and PSC pending states.
Resolve common Cloud SQL for PostgreSQL connectivity issues when integrating Cloud SQL with Atlan. Find the symptom you're seeing in the quick index - each entry includes the checks you can run yourself before opening a ticket.
Quick index
| You see | Most likely cause | Jump to |
|---|---|---|
app internal error: 500 on Test connection; Host is a 10.x / 172.x / 192.168.x address | Private IP entered in Direct mode - unreachable from Atlan | Private IP in Direct mode |
"Not able to authenticate" but the details mention ConnectionTimeout | Network path blocked - not a credential problem | Timeout dressed as auth failure |
Error text ends in SSL off | Server requires SSL; Atlan connection has SSL disabled | SSL required |
IAM auth: role … is not permitted to log in | IAM identity not added as a database user | IAM login |
| Agent-mode runs hang for ~24 h, or "succeed" with no assets | Workflow pointed at a wrong/retired agent queue | Silent agent hangs |
| PSC set up, but connections time out | Endpoint still pending acceptance | Pending PSC endpoint |
| Worked for months, broke after a restart/maintenance, nothing changed on your side | Private IP drift, or an Atlan-side change | Sudden breakage |
Error mentions an internal address like dial tcp 172.20.x.x:443: connect: connection refused | Atlan-side internal fault - not your network | Internal errors |
Private IP entered in Direct mode
Symptom. Test connection fails immediately with a generic error:
app internal error: 500
Check yourself. Look at the Host field. Does it start with 10., 172.16–31., or 192.168.? Those are private addresses - they only exist inside your own network, and Atlan's cloud cannot route to them. No credential, port, or SSL change will fix this.
Fix. Either switch the extraction method to Self-Deployed Runtime and select an agent that runs inside your network (guide), or enable a public IP on the instance and follow the public IP guide. This exact scenario is the most common first-time-setup failure for this connector.
Timeout dressed up as authentication failure
Symptom. The UI says your credentials are wrong, but the fine print says otherwise:
Not able to authenticate your credentials - app internal error: 500 -
map[details:(psycopg.errors.ConnectionTimeout) connection timeout expired ...]
Why. The connector never reached the database, so authentication never started - the "authenticate" wording is misleading. Causes in order of likelihood: Atlan's IPs missing from (or partially missing from) your authorized networks; a firewall between Atlan and the instance; the instance's IP changed (see below); the wrong port.
Check yourself.
- Compare your instance's authorized networks against the published Atlan IPs - all of them, not just some.
- Confirm the Host is the instance's current public IP (Overview page) and the port matches.
- Credentials working from your laptop prove the credentials, not the path - your laptop's IP is allowlisted differently than Atlan's.
Server requires SSL, connector has SSL off
Symptom. Test authentication or preflight fails with an error like:
FATAL: pg_hba.conf rejects connection for host "…", user "atlan_user",
database "…", SSL off
Why. Your instance (or a specific database on it) only accepts encrypted connections - on Cloud SQL that's the "Allow only SSL connections" setting. The connector tried without SSL, and the server refused before checking the password.
Fix. Enable SSL in the Atlan connection settings and retest. Don't weaken the server-side SSL requirement to make the error go away.
IAM auth: role is not permitted to log in
Symptom.
FATAL: role "example-sa@example-project.iam" is not permitted to log in
Why. IAM database authentication needs the identity in two places: an IAM role in the project and a database user on the instance. Only the first was done.
Fix. Cloud SQL console → your instance → Users → Add user account → Cloud IAM, add the user or service account, then grant it the schema permissions from Set up Cloud SQL for PostgreSQL. Also confirm you supplied the instance connection name in the connection config.
Agent-mode runs hang or "succeed" doing nothing
Symptom. After installing or migrating a self-deployed runtime: runs that used to take an hour sit at 10–22 hours, stop at almost exactly 24 hours, or complete "successfully" with no assets updated. Logs show little or nothing.
Why. The workflow is queued for an agent that no longer exists (renamed, migrated, or misconfigured). Nothing is listening on the queue, so the run waits silently until the platform's ~24-hour timeout.
Fix. In the connection/workflow config, verify the selected agent is the one currently online. After any agent migration, re-check every connection that used the old agent - they don't repoint themselves. If the config looks right but runs still hang, open a ticket and say explicitly "runs appear queued for a dead agent queue" - it routes the investigation correctly on the first pass.
PSC endpoint stuck in pending
Symptom. Everything was created on both sides, but connections time out.
Check yourself (Google Cloud console): open your PSC service attachment → Connected endpoints. Is Atlan's endpoint Accepted - or still Pending?
Fix. Accept the connection (or add Atlan's project ID to the accepted-projects list, then accept). Nothing accepts itself; someone with permissions on the attachment must click the button. If it already shows Accepted, reply on your support ticket and ask Atlan to verify the endpoint state from its side.
It worked for months, then broke overnight
- Did the database restart or go through maintenance? Private IPs can change across restarts. If anything pins the old IP - agent config, DNS record, Atlan-side hosted zone - update it (see Special cases).
- Did a published Atlan value change? Check the changelog on the Atlan Network Details page - changes are announced 30 days ahead by email to tenant admins; check spam and distribution lists.
- Did your team edit the authorized-networks list? Remember that some tools replace the whole list rather than appending - an unrelated change may have dropped Atlan's entries.
- Still unexplained → open a ticket with the details below. Simultaneous failures across all your connections with no change on your side can also be an Atlan-side regression; the support team can correlate.
Errors that are Atlan's problem, not yours
Symptom. The error text references infrastructure you don't own, e.g.:
Get "https://172.20.x.x:443/api/v1/namespaces/default/configmaps/...":
dial tcp 172.20.x.x:443: connect: connection refused
Why. That's an internal Atlan-platform address (a Kubernetes API call), not your database. Your network settings cannot cause or fix it.
Fix. Don't burn days re-auditing your firewall. Open a ticket, paste the full error, and state that it references an internal Atlan address.
Opening ticket that gets solved fast
If you still need support, include these six things - they usually turn a multi-day exchange into one reply:
- Your Atlan tenant URL and a link to the failing workflow run
- Connectivity method: Direct over public IP / self-deployed runtime / Private Service Connect
- Whether your Cloud SQL instance has a public IP, private IP, or both - and whether "Allow only SSL connections" is on
- The exact error text from the workflow logs (the details, not just "error 500")
- Auth method (Basic / IAM user / IAM service account / WIF) and, for IAM, the instance connection name
- Whether it ever worked, and if so when it stopped - plus any restarts, maintenance, or migrations around that time