Skip to content

Athena Troubleshooting

Connection failures from AWS are translated by Qualytics into concise, actionable messages prefixed with AWS connection failed (Athena):. For the common credential, IAM Role, permission, and S3 output errors, Qualytics shows the translated message instead of the raw AWS SDK trace (canonical strings, signatures, request IDs).

Common Errors

Wrapped error message Likely Cause Fix
The Secret Access Key does not match the Access Key ID provided Mismatched key pair, changed or expired credentials, or the Secret Access Key was copied with a typo, trailing space, or stray newline Re-copy both the Access Key ID and the Secret Access Key from the IAM console and ensure they belong to the same identity
The AWS Access Key ID is not valid The Access Key ID does not exist, was deleted, or was deactivated Generate a new access key in IAM and update the connection credentials
The AWS credentials are not recognized Either the Access Key ID or the Secret Access Key is incorrect — AWS rejected the credentials before evaluating any IAM policy Verify both values were copied correctly and have not been changed
The AWS session or temporary credentials have expired The STS session associated with the credentials (assumed role, SSO, or temporary key) reached its TTL Generate new temporary credentials and update the connection
The base credentials are not authorized to assume the specified IAM Role The Access Key ID and Secret Access Key supplied to Qualytics do not have permission to assume the configured Role ARN Verify the Role ARN is correct, and update the role's trust policy to allow the calling IAM identity to assume it
The pod's web identity (IRSA) is not authorized to assume the specified IAM Role The Qualytics pod's IRSA service account is not trusted by the role In the role's trust policy, add the EKS OIDC provider and the service account used by the Qualytics pod
The IAM Role has a malformed trust policy The trust policy on the Role ARN has an invalid principal or malformed JSON Open the role in IAM, fix the trust policy, and confirm the principal references a valid ARN
The AWS credentials are valid but lack the required permissions The IAM identity authenticated successfully but is missing one or more required Athena, Glue, or S3 actions Compare the attached policy against the Example IAM Policy and grant the missing actions
Athena cannot write query results to the configured S3 output location The IAM identity lacks s3:PutObject on the S3 Output Location bucket prefix, or the bucket policy denies writes from the calling identity Verify the S3 Output Location is reachable and that s3:PutObject is granted on the bucket prefix

Note

Less common AWS errors that do not match one of the patterns above are shown as the original message from the JDBC driver. The wrapping covers the credential and permission cases reported most frequently.

Detailed Notes

Credential errors

If the wrapped message describes a key pair mismatch, an invalid Access Key ID, unrecognized credentials, or an expired session, AWS rejected the request at the authentication layer — before any IAM policy was evaluated. Adjusting permissions will not help; focus on the credentials themselves:

  • Re-copy the Access Key ID and Secret Access Key, watching for stray whitespace, trailing newlines, or truncated characters.
  • Confirm the Access Key ID and Secret Access Key belong to the same IAM identity.
  • If your access keys come from a temporary STS session (assumed role or SSO), the connector cannot accept a session token directly. Switch the connection to IAM Role authentication (Qualytics refreshes STS credentials automatically), or generate long-lived access keys for a service IAM user.
  • If credentials were recently changed, update the connection with the new values.

Note

Authentication errors occur before any IAM permission policy is evaluated. Modifying policies will not resolve them — only correcting the credentials does.

IAM Role errors

If you selected IAM Role authentication and the wrapped message mentions assuming a role, IRSA, or a malformed trust policy, the credentials reached AWS but STS refused to issue session credentials for the role:

  • Base credentials not authorized: The IAM user behind the Access Key ID and Secret cannot assume the Role ARN. Add the user (or its account) as a trusted principal in the role's trust policy.
  • IRSA not authorized: The Qualytics pod uses an IRSA service account that the role does not trust. Update the trust policy to include your cluster's EKS OIDC provider ARN and the Qualytics service account.
  • Malformed trust policy: The role's trust policy has invalid JSON or an unknown principal. Open the role in IAM and fix the trust policy document.

Tip

Trust policy errors come from STS — the Athena JDBC driver is never reached. The wrapped message names the role and the failing condition, which is faster than reading the raw STS exception.

Permission errors

If the wrapped message states that credentials are valid but lack the required permissions, AWS authenticated the identity but denied authorization on a specific Athena, Glue, or S3 action.

S3 output location errors

If the wrapped message reports that Athena cannot write to the configured output location, the issue is with the S3 bucket rather than Athena or Glue.

  • The path must follow the format s3://bucket/prefix/, including the trailing slash.
  • The bucket must already exist — Qualytics does not create it.
  • The bucket must be in the same AWS region as the Athena workgroup.
  • The IAM identity must hold s3:PutObject on arn:aws:s3:::<bucket>/<prefix>/*.

Tip

You can verify the bucket exists and confirm its region with aws s3api get-bucket-location --bucket <YOUR_BUCKET> in the AWS CLI.

Diagnostic order

The structure of the wrapped message indicates which layer failed and where to look first:

Message describes… Layer that failed Where to look
Access Key ID, Secret Access Key, or expired session Authentication Verify the credentials themselves; IAM policies are not evaluated at this stage
Assuming an IAM Role, IRSA, or trust policy STS / role assumption Verify the Role ARN, the role's trust policy, and that the calling identity (or IRSA service account) is trusted
Credentials are valid but lack required permissions Authorization Compare the IAM policy to the minimum-permissions tables and use CloudTrail to identify the missing action
Athena cannot write query results to the S3 output location S3 configuration Confirm the bucket name, path format, region, and s3:PutObject permission on the prefix

Tip

Investigate in the order AWS evaluates requests — authentication first, role assumption second, authorization third, then execution. Resolving credential errors before policy errors avoids chasing IAM changes that wouldn't have helped.