Troubleshooting Amazon Redshift connectivity

✦TL;DR

Symptom-first troubleshooting for Amazon Redshift connectivity - timeouts, IAM policy scope, role trust, DNS, password failures, Serverless quirks, and sudden breakage.

||

|Connect

Resolve common Amazon Redshift connectivity issues when integrating Redshift 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.

Read this first: "authentication failed" often isn't

Atlan currently wraps several network errors in an authentication-failure banner (ATLAN-CLIENT-401-02: SQL client authentication failed). Always read the text after the banner. If it says timeout expired or could not translate host name, your credentials are fine - the network path is the problem.

Quick index

You see	Most likely cause	Jump to
…port 5439 failed: timeout expired (inside an "authentication failed" banner)	Network path blocked - private cluster, security group, or PrivateLink component	Connection timeouts
AccessDenied … GetClusterCredentials … not authorized	IAM policy doesn't cover every database/user the crawl touches	IAM policy scope
Error while retrieving credential via role ARN / not authorized to perform: sts:AssumeRole	Role trust policy not wired to Atlan's tenant role + external ID	Role trust
could not translate host name … to address / Unknown host	DNS: wrong hostname, recreated cluster, or private-DNS fault	DNS & hostnames
FATAL: password authentication failed for user "…"	Credential rotated or user removed on the cluster	Password failures
Serverless: Failed to assume role in any region, or calls hitting the wrong AWS API	Serverless not detected - workgroup/hostname issue	Serverless quirks
Worked for months, broke overnight, "nothing changed"	Something changed: cluster migration, credential rotation, SG edit - or an old failure newly surfaced	Sudden breakage
Check failed! Please grant select permission on pg_catalog.… (preflight)	Missing database grants - not a network issue	Preflight checks for Amazon Redshift

Connection timeouts (#1 issue)

Symptom. Test connection or preflight fails after ~30 seconds with:

ATLAN-CLIENT-401-02: SQL client authentication failed:
(psycopg2.OperationalError) connection to server at "<host>" (<ip>),
port 5439 failed: timeout expired

Why. Atlan's TCP connection never got an answer. Despite the "authentication failed" wrapper, no credential was ever checked. Work through these in order:

1. Is the cluster publicly accessible? (AWS console → cluster → Properties.) If not, no amount of security-group allowlisting can ever work - even 0.0.0.0/0. A private cluster needs the private network link or an agent.
2. Public path: does the security group permit every Atlan egress IP on port 5439? One missing IP = intermittent timeouts. Check subnet network ACLs too.
3. Private link (the IP in the error is a 10.x address): something in the endpoint chain changed. Ask your cloud team to verify, in order: the endpoint/endpoint-service connection state is available/accepted; NLB targets (if any) are healthy on 5439; the cluster's security group permits the endpoint/NLB subnets; subnet NACLs and return routes are intact. Timeouts here are customer-side path changes far more often than Atlan-side ones.
4. Still stuck? Note whether the resolved IP in the error is private (10.x) or public - include that in your ticket; it halves the diagnosis time.

IAM policy scope - GetClusterCredentials denied

Symptom. Preflight or crawl fails with:

An error occurred (AccessDenied) when calling the GetClusterCredentials
operation: User: arn:aws:sts::<account>:assumed-role/<role>/atlan_jdbc_metadata_extractor
is not authorized to perform: redshift:GetClusterCredentials on resource:
arn:aws:redshift:<region>:<account>:dbname:<cluster>/<database>

Why. Two things trip people up:

• atlan_jdbc_metadata_extractor is the assumed-role session name Atlan uses - it's not, and doesn't need to be, your database user. Seeing it in the error is normal.
• When crawling multiple databases, Atlan calls GetClusterCredentials for every database it enumerates. Your IAM policy must cover the dbname: ARN of each crawled database and the dbuser: ARN of the Atlan user - a policy scoped to one database fails the moment the crawl touches a second.

Fix. Either widen the policy to all crawled dbname:/dbuser: ARNs (the resource named in the error is the exact one missing), or narrow the crawler's include-database filter to match the policy.

"Resource": [
  "arn:aws:redshift:us-east-1:111111111111:dbuser:example-cluster/atlan_user",
  "arn:aws:redshift:us-east-1:111111111111:dbname:example-cluster/analytics",
  "arn:aws:redshift:us-east-1:111111111111:dbname:example-cluster/marts"
]

Role trust - sts:AssumeRole refused

Symptom. HEKA-401-00-001 … Error while retrieving credential via role ARN, or an AWS-side error that a role …is not authorized to perform: sts:AssumeRole.

Why. Your role's trust policy doesn't trust the exact Atlan identity that's asking. The trusted principal is a tenant-specific Atlan role ARN - you must get it (plus the external ID) from Atlan support; guessing a generic Atlan account fails.

Fix / self-check.

• Ask support for your tenant's role ARN and external ID; compare character-by-character with your trust policy.
• Avoid IP conditions in the trust policy. A condition like "aws:SourceIp": "203.0.113.10/32" breaks silently if your tenant's egress IP ever changes.
• Using IAM role auth on a provisioned cluster? Fill the crawler's Cluster ID field. Without it, the credentials call can resolve to the wrong AWS region and fail even though every policy is correct.

DNS and hostname issues

Symptom.

could not translate host name "example-redshift-endpoint-abc123.us-east-1
.redshift.amazonaws.com" to address: Name or service not known
-- or: Unknown host. Please check hostname.

• Recreated or migrated cluster? A new cluster gets a new endpoint hostname - a connection pointing at the old one fails exactly like this. Update Host Name in the connection settings (see sudden breakage).
• Private hostname? The private-link hostname resolves only inside Atlan's network - nslookup from your laptop failing is expected. If Atlan's own resolution fails (test connection errors with "Name or service not known" on a hostname containing -endpoint-), that's usually an Atlan-side private-DNS fault: contact support instead of debugging credentials.
• Typo check. Compare the Host Name field character-by-character with the value in the AWS console (or on your support ticket, for private links).

Password authentication failures

Symptom.

FATAL: password authentication failed for user "atlan_user"
-- Preceded by sslmode=prefer fallback noise you can ignore:
-- "SSL SYSCALL error" / "no pg_hba.conf entry ... SSL off"

Why. The network path is healthy - Redshift answered and rejected the credential. This is almost always a password rotated (or service user dropped) on the cluster without updating the Atlan connection. Scheduled workflows then fail on every run.

Fix. Re-enter the current password in the connection's credential settings, run Test connection, and the next scheduled run recovers on its own.

Seeing "IAM:atlan_user" or "IAMR:atlan_role" in the error?

That prefix means IAM authentication worked - AWS issued short-lived credentials and Redshift maps them to a user named IAM:<user> (or IAMR:<role> on Serverless). The rejection is cluster-side: confirm that database user/role exists and matches your IAM policy's dbuser: ARN.

Redshift Serverless quirks

• Failed to assume role in any region or calls to redshift:GetClusterCredentials instead of redshift-serverless:GetCredentials: Atlan didn't detect the target as Serverless. Detection keys off the hostname - a standard Serverless endpoint (containing redshift-serverless.amazonaws.com) autodetects; an opaque custom VPC-endpoint hostname doesn't. Fix: use a Redshift-managed endpoint whose hostname preserves the redshift-serverless form, fill the Workgroup field where available, and set Deployment Type = Serverless.
• IAM role auth on Serverless: no username field - the role connects as IAMR:<role-name>, and the role must carry the tag RedshiftDbRoles: atlan_role.
• Miner: uses SYS_QUERY_HISTORY, SYS_QUERY_TEXT, and SYS_CONNECTION_LOG instead of the provisioned stl_* tables; the SYSLOG/stl_* grants don't apply.

It worked for months, then broke overnight

"Nothing changed on the system's side" - but usually something had. Check, in order of real-world frequency:

1. Credential rotation. Did anyone rotate the Atlan service user's password or delete the user? (Password failures - the most common cause.)
2. Cluster migration or resize. Recreating a cluster (even "the same" one on new node types) changes its hostname and invalidates private-link grants. Update the Host Name and repeat the grant/endpoint steps for the new cluster.
3. Network edits. Security group, NACL, endpoint, or NLB changes on the private path - timeouts on a 10.x address point here (Connection timeouts).
4. It was never working. Some older pipelines reported "Succeeded" while silently failing; platform upgrades then surfaced the pre-existing breakage as new failures. If the "break" coincided with an Atlan platform migration notice, the root cause may predate it - the fixes listed here still apply.

Opening ticket that gets solved fast

If you still need support, include these five things - they usually turn a multi-day exchange into one reply:

• Your Atlan tenant URL and the failing workflow run link
• Connectivity method (public + allowlist / private network link / agent) and deployment type (Provisioned RA3, DC2, or Serverless)
• Authentication method (Basic / IAM user / IAM role) and the exact error text from the workflow logs - including the part after any "authentication failed" banner
• The resolved IP shown in the error (private 10.x vs public tells support which path to inspect)
• Whether it ever worked, when it stopped, and any change around that date (rotation, migration, network edits)

Other known issues

Why do I get error when querying external schema in Amazon Redshift?

Atlan currently does not support search paths for external schemas and tables in Amazon Redshift.

To query an external schema in Amazon Redshift from Atlan, you need to write the query in Data Exploration with the fully qualified name and keep the editor context empty - for example, select * db.schema.table and as shown here:

Does Atlan support connecting to Amazon Redshift via SSL?

Yes, Atlan supports connecting to Amazon Redshift over the Secure Sockets Layer (SSL) protocol. If your Amazon Redshift cluster is configured to require an SSL connection, with the require_SSL parameter set to true, Atlan will be able to connect to your cluster.