Skip to content

Redshift Troubleshooting

Connection failures from Redshift fall into four categories: credential errors (the database password is rejected, or AWS STS denies role assumption), permission errors (the identity authenticated but lacks the database grants the operation needs), connection errors (the cluster is not reachable from the dataplane), and validation errors (Qualytics rejected the request before it reached Redshift). The structure of the error message indicates which layer failed.

Common Errors

Error Likely Cause Fix
FATAL: password authentication failed Incorrect username or password (Password mode). Verify the credentials. Confirm the user exists in the cluster. Check for trailing whitespace when copying.
permission denied for schema The user lacks USAGE on the target schema. Run GRANT USAGE ON SCHEMA <schema_name> TO <user>.
permission denied for relation The user lacks SELECT on one or more tables. Run GRANT SELECT ON ALL TABLES IN SCHEMA <schema_name> TO <user>.
permission denied to create relation The enrichment user lacks CREATE on the schema. Run GRANT CREATE ON SCHEMA <schema_name> TO <user>.
Connection refused Cluster not reachable. Security group blocks the dataplane IP, the cluster is paused, or it is not publicly accessible. Add the dataplane IP to the inbound rules of the cluster's security group. Resume the cluster if paused.
AWS connection failed (Redshift): sts:AssumeRole denied The role's trust policy does not list the dataplane identity as a trusted Principal. Update the role's trust policy to allow the dataplane identity to assume it. See IAM Role Authentication.
AWS connection failed (Redshift): External ID mismatch The External ID entered in the connection form does not byte-match the sts:ExternalId condition in the trust policy. Re-copy the External ID. Watch for whitespace and copy-paste artifacts.
AWS connection failed (Redshift): AssumeRoleWithWebIdentity denied IRSA (used by EKS deployments) is not allowed by the role's trust policy. Update the trust policy to include the EKS OIDC provider ARN and the Qualytics service account.
Invalid or missing authentication_type. Allowed values: ['BASIC', 'IAM_ROLE'] The API payload sent an unsupported authentication_type value. Use BASIC or IAM_ROLE. The default when omitted is BASIC.
Invalid schema provided for connection of type 'redshift' required fields: [..., 'role_arn'] The API payload set authentication_type: IAM_ROLE without role_arn. Include connection.parameters.role_arn in the payload, or switch to BASIC and supply username and password.

Note

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

Detailed Notes

Credential errors

These appear in Password mode. The request never reaches AWS STS, so the failure is at the pure Redshift database layer:

  • Incorrect password: the password does not match the one set for the user. Re-copy it, watching for trailing whitespace or truncated characters.
  • User does not exist: the username was misspelled or was never created in the cluster.
  • Master user required: some administrative operations require the cluster's master user credentials.

Note

Authentication errors occur before any database privileges are evaluated. Modifying GRANTs will not resolve them. Only correcting the credentials does.

IAM Role errors

When IAM Role authentication is selected, the JDBC driver first calls AWS STS to obtain session credentials for the target role. If STS refuses, the connection fails before any Redshift query runs. EKS-deployed setups use IRSA (IAM Roles for Service Accounts) so the dataplane's pod identity is the principal that STS evaluates:

  • sts:AssumeRole denied: the role's trust policy does not list the dataplane identity as a trusted Principal. Add the dataplane identity (or its account) to the trust policy.
  • External ID mismatch: the External ID entered in the connection form does not match the sts:ExternalId condition in the trust policy, byte for byte. Re-copy the value, watching for whitespace.
  • AssumeRoleWithWebIdentity denied: in EKS deployments, IRSA uses a service account that the role does not trust. Update the trust policy to include the cluster's EKS OIDC provider ARN and the Qualytics service account.
  • Malformed trust policy: the trust policy has invalid JSON or an unknown principal ARN. Open the role in IAM and fix the policy document.
  • Expired session token: the STS session reached its TTL. Re-test the connection; Qualytics requests a fresh session on each test.

For the full setup, including the trust policy template and the AWS-side permissions, see IAM Role Authentication.

Permission errors

The identity authenticated successfully but Redshift denied the action. These come from the database layer, after AWS (in IAM Role mode) has already issued the temporary credentials:

  • Missing USAGE on schema: the user cannot reach any object in the schema, even if table-level grants exist.
  • Missing SELECT on tables: the user reaches the schema but cannot read specific tables.
  • Missing CREATE on schema (enrichment): the enrichment user cannot create the _qualytics_* metadata tables.
  • Default privileges not set: new tables added by other users after the initial grant are not automatically readable. Use ALTER DEFAULT PRIVILEGES so future tables inherit access.
  • Table owner mismatch: the table was created by a different user, and default privileges were not granted on its behalf.

Use Redshift system tables like pg_class, information_schema.role_table_grants, or audit logging to identify which permission is missing.

Connection errors

The credentials and IAM setup are correct, but the dataplane cannot reach the cluster:

  • Security group blocks inbound: the cluster's VPC security group does not allow inbound connections from the dataplane on the Redshift port (default 5439). Add the dataplane IP (or subnet) to the inbound rules.
  • Cluster not publicly accessible: the cluster was created without public accessibility and the dataplane is connecting from outside the VPC. Either enable public accessibility, or place the dataplane inside the same VPC (or a peered VPC).
  • Cluster paused: the cluster is in a paused state. Resume it from the Redshift console.
  • VPC endpoint or custom DNS alias: the IAM Role path does not support VPC endpoint URLs (vpce-…) or custom Route 53 aliases. Use the canonical <cluster>.<account>.<region>.redshift.amazonaws.com (or <workgroup>.<account>.<region>.redshift-serverless.amazonaws.com) endpoint.

Validation errors

Qualytics validates the connection payload before sending it to Redshift. A 422 response means the request was rejected at the API layer:

  • Invalid or missing authentication_type. Allowed values: ['BASIC', 'IAM_ROLE']: the payload sent an unsupported value (or a typo) for connection.parameters.authentication_type. Use BASIC or IAM_ROLE. When omitted, the default is BASIC.
  • Invalid schema provided for connection of type 'redshift' required fields: [..., 'role_arn']: the payload set authentication_type: IAM_ROLE without role_arn. Include connection.parameters.role_arn, or switch to BASIC and supply username and password.

These errors do not reach Redshift. Once the payload is corrected, the connection proceeds to the credential and permission layers.

Diagnostic order

Investigate in the order AWS and Redshift evaluate the request. Resolving credential and STS errors before permission errors avoids chasing GRANT changes that would not have helped:

Message describes... Layer that failed Where to look
FATAL: password authentication failed, user does not exist Authentication (DB layer) Verify the Redshift credentials and confirm the user exists. Check the master user state if administrative actions are required.
Assuming an IAM Role, IRSA (used by EKS), or the trust policy STS / role assumption Verify the Role ARN, the role's trust policy, and that the dataplane identity is trusted. Confirm the External ID matches byte for byte.
permission denied on a schema or relation Authorization (DB layer) Verify GRANTs on the schema (USAGE) and tables (SELECT). Check default privileges for future tables and confirm table ownership.
Connection refused, security group, paused cluster Network / cluster state Confirm the security group allows inbound from the dataplane subnet on port 5439. Confirm the cluster is running and the endpoint is reachable.
Invalid authentication_type or missing role_arn Validation (Qualytics API) Correct the payload before re-submitting; the request never reaches Redshift.

See also Permissions and Authentication for the connection-side configuration that backs each layer.