cube-js/cube · error · Error

CUBEJS_DB_NAME is required for IAM authentication

Error message

CUBEJS_DB_NAME is required for IAM authentication

What it means

Temporary credentials from GetClusterCredentials are scoped to a specific database. The provider requires options.dbName so it can request credentials for the right database, and throws at construction if it is absent.

Source

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

  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,
          ...(options.assumeRoleExternalId && { ExternalId: options.assumeRoleExternalId }),
        },
      });
    }
  }

View on GitHub (pinned to 7d981676b3)

Solutions

1. Set CUBEJS_DB_NAME to the target Redshift database
2. Pass dbName explicitly in RedshiftIAMCredentialProviderOptions
3. Ensure the database exists and the IAM role is allowed GetClusterCredentials for that dbuser/dbname

Example fix

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

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

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

When it happens

Trigger: new RedshiftIAMCredentialsProvider({...}) with region and clusterIdentifier set but dbName undefined — typically CUBEJS_DB_NAME unset.

Common situations: IAM auth enabled but the database name env var missing or renamed; deploying with only connection-string style config that the IAM provider does not read.

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

• CUBEJS_DB_REDSHIFT_AWS_REGION is required for IAM authentica
• CUBEJS_DB_REDSHIFT_CLUSTER_IDENTIFIER is required for IAM au
• Unsupported configuration exportBucket, some configuration k
• Unsupported EXPORT_BUCKET_TYPE, supported: ${supportedBucket
• Unsupported configuration exportBucket, some configuration k

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