cube-js/cube · error · Error

CUBEJS_DB_REDSHIFT_AWS_REGION is required for IAM authentica

Error message

CUBEJS_DB_REDSHIFT_AWS_REGION is required for IAM authentication

What it means

RedshiftIAMCredentialsProvider generates temporary Redshift credentials via AWS GetClusterCredentials, which requires the cluster's AWS region. Constructing the provider without options.region fails fast with this message pointing at the CUBEJS_DB_REDSHIFT_AWS_REGION env var.

Source

Thrown at packages/cubejs-redshift-driver/src/RedshiftIAMCredentialsProvider.ts:37

// Refresh 1m before expiry
const REFRESH_BUFFER_MS = 60 * 1000;

export class RedshiftIAMCredentialsProvider implements RedshiftCredentialsProvider {
  protected readonly region: string;

  protected readonly clusterIdentifier: string;

  protected readonly dbName: string;

  protected readonly awsCredentials?: ReturnType<typeof fromTemporaryCredentials>;

  protected cached: CachedCredentials | null = null;

  protected inflightRefresh: Promise<CachedCredentials> | null = null;

  public constructor(options: RedshiftIAMCredentialProviderOptions) {
    if (!options.region) {
      throw new Error('CUBEJS_DB_REDSHIFT_AWS_REGION is required for IAM authentication');
    }

    if (!options.clusterIdentifier) {
      throw new Error(
        'CUBEJS_DB_REDSHIFT_CLUSTER_IDENTIFIER is required for IAM authentication'
      );
    }

    if (!options.dbName) {
      throw new Error(
        'CUBEJS_DB_NAME is required for IAM authentication'
      );
    }

    this.region = options.region;
    this.clusterIdentifier = options.clusterIdentifier;
    this.dbName = options.dbName;

View on GitHub (pinned to 7d981676b3)

Solutions

Set CUBEJS_DB_REDSHIFT_AWS_REGION (e.g. us-east-1) in the Cube process environment
Pass region explicitly in RedshiftIAMCredentialProviderOptions when constructing programmatically
Verify the env var is loaded (docker env, .env file, secrets manager) before app start

Example fix

// before
CUBEJS_DB_REDSHIFT_CLUSTER_IDENTIFIER=my-cluster
// after
CUBEJS_DB_REDSHIFT_AWS_REGION=us-east-1
CUBEJS_DB_REDSHIFT_CLUSTER_IDENTIFIER=my-cluster

Defensive patterns

Strategy: validation

Validate before calling

if (!process.env.CUBEJS_DB_REDSHIFT_AWS_REGION) {
  throw new Error('CUBEJS_DB_REDSHIFT_AWS_REGION must be set for IAM auth');
}

Type guard

function hasRegion(o: { region?: string }): o is { region: string } {
  return typeof o.region === 'string' && o.region.length > 0;
}

Prevention

Set region (and cluster id, db name) together whenever enabling IAM auth
Include IAM env vars in .env.example and deployment templates
Fail fast with a startup config check script

When it happens

Trigger: new RedshiftIAMCredentialsProvider({ ... }) called during driver setup with IAM auth enabled when options.region is undefined — typically because CUBEJS_DB_REDSHIFT_AWS_REGION is unset.

Common situations: Enabling IAM authentication (CUBEJS_REDSHIFT_AUTH='iam' style setups) but forgetting the region env var; region configured for one environment but not another (staging/prod).

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

AI-assisted analysis of cube-js/cube@7d981676b3 (2026-09-02). Data as JSON: /api/errors/ff797bf9560e0544. Report an issue: GitHub.