cube-js/cube · critical · Error

The ${keyByDataSource('CUBEJS_DB_NAME', dataSource)} is requ

Error message

The ${keyByDataSource('CUBEJS_DB_NAME', dataSource)} is required and missing.

What it means

cubejsDbName reads CUBEJS_DB_NAME (per data source) and throws when a caller marks it required via the { required: true } option but the variable is unset or empty. The error names the resolved data-source-specific variable, e.g. CUBEJS_DS_MYSQL_DB_NAME.

Source

Thrown at packages/cubejs-backend-shared/src/env.ts:578

  }: DataSourceOpts) => (
    get(keyByDataSource('CUBEJS_DB_PASS', dataSource, preAggregations)).asString()
  ),

  /**
   * Database name.
   */
  dbName: ({
    required,
    dataSource,
    preAggregations,
  }: {
    dataSource: string,
    required?: boolean,
    preAggregations?: boolean,
  }) => {
    const val = get(keyByDataSource('CUBEJS_DB_NAME', dataSource, preAggregations)).asString();
    if (required && !val) {
      throw new Error(
        `The ${
          keyByDataSource('CUBEJS_DB_NAME', dataSource)
        } is required and missing.`
      );
    }
    return val;
  },

  /**
   * Database name.
   * @deprecated
   */
  dbSchema: ({
    required,
    dataSource,
    preAggregations,
  }: {
    dataSource: string,

View on GitHub (pinned to 7d981676b3)

Solutions

1. Set CUBEJS_DB_NAME (or CUBEJS_DS_<DATASOURCE>_DB_NAME) in the environment before startup.
2. Verify which data source name is being passed to the accessor matches the prefix in your env vars (case-sensitive toUpperCase).
3. Check that your secret/config map is actually mounted and loaded (docker exec / kubectl exec and echo the var).
4. If the database name is supplied by driver config instead of env, drop required: true.

Example fix

// before (deployment)
# CUBEJS_DB_NAME missing
// after
docker run -e CUBEJS_DB_NAME=analytics ...

const dsKey = `CUBEJS_DS_${dataSource.toUpperCase()}_DB_NAME`;
if (!process.env[dsKey] && !process.env.CUBEJS_DB_NAME)
  throw new Error(`Missing ${dsKey} (or CUBEJS_DB_NAME) for data source ${dataSource}`);

try {
  const dbName = getEnv('dbName', { dataSource, required: true });
} catch (e) {
  if (String(e.message).includes('DB_NAME') && e.message.includes('required and missing')) {
    console.error(`Provide ${keyByDataSource('CUBEJS_DB_NAME', dataSource)} in the environment`);
    process.exit(1);
  }
  throw e;
}

When it happens

Trigger: Calling getEnv('dbName') or the db-name accessor with required: true while neither CUBEJS_DB_NAME nor CUBEJS_DS_<DATASOURCE>_DB_NAME is set in the environment for that data source.

Common situations: Deploying without copying the full .env; Kubernetes secret not mounted; using only a DS-specific name while the code checks the generic one for a dataSource whose prefix differs; renaming databases during migrations.

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.

Related errors

• The ${keyByDataSource('CUBEJS_DB_SCHEMA', dataSource)} is re
• The ${keyByDataSource('CUBEJS_DATABASE', dataSource)} is req
• The ${origin} environment variable can not be converted for
• Value "${value}" is not valid for CUBEJS_MAX_REQUEST_SIZE. M
• The ${keyByDataSource('CUBEJS_DB_SSL', dataSource)} must be

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