cube-js/cube · error · Error

CUBEJS_DB_REDSHIFT_CLUSTER_IDENTIFIER is required for IAM au

Error message

CUBEJS_DB_REDSHIFT_CLUSTER_IDENTIFIER is required for IAM authentication

What it means

AWS GetClusterCredentials needs the cluster identifier of the target Redshift cluster to mint temporary DB credentials. The provider throws this at construction time when options.clusterIdentifier is missing.

Source

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

  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;

    if (options.assumeRoleArn) {
      this.awsCredentials = fromTemporaryCredentials({
        params: {
          RoleArn: options.assumeRoleArn,

View on GitHub (pinned to 7d981676b3)

Solutions

Set CUBEJS_DB_REDSHIFT_CLUSTER_IDENTIFIER to the Redshift cluster id
Pass clusterIdentifier explicitly in RedshiftIAMCredentialProviderOptions
Confirm the cluster id matches the actual AWS Redshift cluster name

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Prevention

Keep a single checklist of IAM-auth env vars: region, cluster identifier, db name
Validate cluster identifier against the actual AWS console value
Check per-dataSource env overrides resolve for every environment

When it happens

Trigger: new RedshiftIAMCredentialsProvider({...}) with region set but clusterIdentifier undefined — typically CUBEJS_DB_REDSHIFT_CLUSTER_IDENTIFIER unset while IAM auth is enabled.

Common situations: Switching from password auth to IAM auth without adding cluster identifier env; multiple dataSources where only one has the env var configured.

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/bb1fc1240bbbf496. Report an issue: GitHub.