## Troubleshooting Athena connectivity

URL: https://docs.atlan.com/apps/connectors/database/amazon-athena/troubleshooting/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](#role-authentication-failures-heka-401--aaf-hdl-001) |
| Auth passes, crawl fails: *Connection timed out* to `athena.<region>.amazonaws.com:443` | PrivateLink endpoint / security-group gap | [JDBC timeouts](#jdbc-connection-timeouts-auth-ok-crawl-fails) |
| `AccessDeniedException` on `glue:GetDatabases` / `glue:GetTables`, or LF "no privilege on specified resource", or `kms:Decrypt` | Missing Glue / Lake Formation / KMS permission | [Permission gaps](#permission-gaps-mid-crawl-test-passed) |
| `Rate exceeded`, `ExpiredTokenException`, or a huge crawl failing near the end | Large-catalog scale limits | [Special cases](https://docs.atlan.com/llms/connectors/amazon-athena/special-cases/llms.txt) |
| 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](#when-its-not-you-platform-side-signatures) |
| Worked for months, broke overnight, nothing changed on your side | Key rotation, policy edit, or Atlan-side change | [Sudden breakage](#it-worked-for-months-then-broke-overnight) |

## 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:

1. **External ID mismatch** - trust policy value ≠ Atlan form value. Compare character-for-character; regenerate in the form and update the trust policy if unsure.
2. **Atlan-side allowlist missing** - Phase 3 of the [role guide](https://docs.atlan.com/llms/connectors/amazon-athena/connect-with-an-iam-role/llms.txt) never happened, or was done for a different tenant. Ask support to confirm your exact role ARN is allowlisted *for this tenant*.
3. **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:**

1. 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.
2. 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.
3. 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.

:::tip Shortcut worth memorizing

**"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](https://docs.atlan.com/llms/connectors/amazon-athena/permissions-and-the-s3-results-bucket/llms.txt) 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

1. **Access keys?** Ask whether your security team rotated the IAM user's keys - the most common cause. Update the connection credentials and re-test.
2. **IAM role?** Ask whether the trust policy, external ID condition, or an attached permission boundary changed; check CloudTrail for denied `AssumeRole` events.
3. **Permissions error naming a specific service?** A policy edit or new Lake Formation/KMS enforcement on your side - match it to the [permission map](https://docs.atlan.com/llms/connectors/amazon-athena/permissions-and-the-s3-results-bucket/llms.txt).
4. **Timeout with private IPs in the log?** Network path change - see [JDBC timeouts](#jdbc-connection-timeouts-auth-ok-crawl-fails) 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, AWS `AccessDeniedException` line, 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](https://docs.atlan.com/llms/connectors/amazon-athena/permissions-and-the-s3-results-bucket/llms.txt))

---