Troubleshooting Athena connectivity
Symptom-first troubleshooting for Amazon Athena connectivity - role authentication failures, JDBC timeouts, permission gaps, platform-side signatures, and sudden breakage.
Resolve common Amazon Athena connectivity issues when integrating Athena with Atlan. Find the symptom you're seeing in the quick index - each entry includes a check you can run before opening a ticket.
Quick index
| You see | Most likely cause | Jump to |
|---|---|---|
Test Authentication fails: HEKA-401-00-001 / "Error while retrieving credential via role ARN" / [AAF-HDL-001] Authentication failed | External ID mismatch, or Atlan-side allowlist missing | Role auth failures |
Auth passes, crawl fails: Connection timed out to athena.<region>.amazonaws.com:443 | PrivateLink endpoint / security-group gap | JDBC timeouts |
AccessDeniedException on glue:GetDatabases / glue:GetTables, or LF "no privilege on specified resource", or kms:Decrypt | Missing Glue / Lake Formation / KMS permission | Permission gaps |
Rate exceeded, ExpiredTokenException, or a huge crawl failing near the end | Large-catalog scale limits | Special cases |
Workflow "Failed" but assets look updated; or sample data fails with HEKA-500-00-002 | Platform-side issue - not your setup | When it's not you |
| Worked for months, broke overnight, nothing changed on your side | Key rotation, policy edit, or Atlan-side change | Sudden breakage |
Role authentication failures (HEKA-401 / AAF-HDL-001)
Symptom. Test Authentication fails immediately. Typical error text:
"errorName":"UNAUTHORIZED",
"errorMessage":"Error while retrieving credential via role ARN",
"errorCode":"HEKA-401-00-001"
-- or --
app validation error: 401 - map[detail:[AAF-HDL-001] Authentication failed: invalid credentials]
Why. The STS AssumeRole handshake failed. The causes, in order of frequency:
- External ID mismatch - trust policy value ≠ Atlan form value. Compare character-for-character; regenerate in the form and update the trust policy if unsure.
- Atlan-side allowlist missing - Phase 3 of the role guide never happened, or was done for a different tenant. Ask support to confirm your exact role ARN is allowlisted for this tenant.
- Wrong principal ARN in your trust policy - retyped or from the wrong tenant. Re-request the node instance role ARN and paste it.
Check yourself. Your AWS admin can look for Atlan's attempts in CloudTrail (event name AssumeRole, your role as resource). Requests arriving and being denied → trust policy/external ID. No requests at all → Atlan-side allowlist or wrong ARN in the Atlan form.
JDBC connection timeouts (auth OK, crawl fails)
Symptom. Authentication and role assumption succeed; the crawl (or its Athena step) fails with:
java.sql.SQLException: [Simba][AthenaJDBC](100131) An error has been thrown
from the AWS SDK client. Unable to execute HTTP request: Connect to
athena.<region>.amazonaws.com:443 [athena.<region>.amazonaws.com/10.x.x.x, ...]
failed: Connection timed out
Why. The hostname resolved to private IP addresses (10.x.x.x) - traffic is routed through a PrivateLink endpoint - and TCP port 443 to those addresses is being dropped. In practice this is a security-group or subnet gap on the VPC interface endpoint, on either side.
Fix, in order:
- Reply on a support ticket quoting the timeout and the private IPs from the log. Ask Atlan to verify the endpoint's security group includes all tenant subnets - this is the most common fix and only Atlan can check it.
- If the endpoint is in your network: your cloud team runs
aws ec2 describe-vpc-endpoints, then confirms the endpoint SG allows inbound TCP 443 from the crawler's source range and that private DNS/host value match. - Not intending to use PrivateLink at all? The private IPs mean an endpoint exists anyway - flag it, since it intercepts Athena traffic whether you meant it or not.
"STS succeeds + JDBC times out" = network, not credentials. Don't rotate keys, don't touch the trust policy - the identity part already worked.
Permission gaps mid-crawl (test passed)
Symptom. Test Authentication passes; the crawl fails partway or catalogs less than expected. The error names the missing permission:
AccessDeniedException ... is not authorized to perform: glue:GetDatabases
-- Lake Formation:
Insufficient permissions to execute the query. Error listing table columns
for catalog awsdatacatalog: Principal does not have any privilege on specified resource
-- KMS-encrypted Glue catalog:
... is not authorized to perform: kms:Decrypt on the resource associated
with this ciphertext (GlueEncryptionException)
-- Results bucket:
Access to the specified S3 resource is denied
Fix. Match the error to the permission map row and grant the missing action. Remember the two the base policy doesn't cover: Lake Formation grants and KMS decrypt - run the two pre-flight CLI checks on the permissions page to detect both up front. An explicit deny on individual databases makes the crawler skip them; align the crawler's include/exclude filters with your permission boundary.
When it's not you: Platform-side signatures
Some failure signatures have been Atlan-side bugs, not customer misconfiguration. If you see one of these, quote the detail below instead of re-auditing your IAM setup:
| Signature | What it was | What to tell support |
|---|---|---|
| IAM Role test-auth fails while IAM User works, right after a UI/platform update | UI form dropped the role ARN/external ID fields (fixed) | "Role fields may not be reaching the connector - please check the auth request payload" |
| Workflow shows Failed but all assets updated fine | Empty-lineage runs mis-marked as failures (fixed) | "Is this the lineage-status issue? Assets updated, status Failed" |
Sample data / querying fails with HEKA-500-00-002 … parameter driver null | Credential template bug after connector migration (fixed) | Quote the HEKA-500 error verbatim |
Access-key connection on an Azure-hosted tenant attempts sts:AssumeRole | Env-var injection bug on Azure tenants (fixed) | "IAM User auth attempting AssumeRole on Azure-hosted tenant" |
It worked for months, then broke overnight
- Access keys? Ask whether your security team rotated the IAM user's keys - the most common cause. Update the connection credentials and re-test.
- IAM role? Ask whether the trust policy, external ID condition, or an attached permission boundary changed; check CloudTrail for denied
AssumeRoleevents. - Permissions error naming a specific service? A policy edit or new Lake Formation/KMS enforcement on your side - match it to the permission map.
- Timeout with private IPs in the log? Network path change - see JDBC timeouts and ask Atlan to check the endpoint security group before changing anything yourself.
Opening ticket that gets solved fast
Athena tickets resolve fastest when support can see the whole chain at once. Include:
- Your Atlan tenant URL and the failing workflow run link
- Auth method (IAM user / IAM role) - and for roles, the role ARN and whether the external ID was regenerated recently
- Network path: default public endpoints or PrivateLink (paste the host value you entered)
- The exact error text from the workflow logs - especially any
HEKA-…/AAF-…code, AWSAccessDeniedExceptionline, or timeout with IP addresses - Whether Test Authentication passes, and whether it ever worked (and when it stopped)
- Whether your account uses Lake Formation or KMS-encrypted Glue (the two CLI checks on the permissions page)