cube-js/cube · error · Error

The ${keyByDataSource('CUBEJS_DATABASE', dataSource)} is req

Error message

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

What it means

cubejsDatabase reads CUBEJS_DATABASE (per data source) and throws when required: true is passed and the variable is unset or empty. CUBEJS_DATABASE is deprecated in favor of CUBEJS_DB_NAME, so this error typically appears with legacy database configuration.

Source

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

  dbDatabase: ({
    required,
    dataSource,
    preAggregations,
  }: {
    dataSource: string,
    required?: boolean,
    preAggregations?: boolean,
  }) => {
    console.warn(
      `The ${
        keyByDataSource('CUBEJS_DATABASE', dataSource)
      } is deprecated. Please, use the ${
        keyByDataSource('CUBEJS_DB_NAME', dataSource)
      } instead.`
    );
    const val = get(keyByDataSource('CUBEJS_DATABASE', dataSource, preAggregations)).asString();
    if (required && !val) {
      throw new Error(
        `The ${
          keyByDataSource('CUBEJS_DATABASE', dataSource)
        } is required and missing.`
      );
    }
    return val;
  },

  /**
   * Database max pool size.
   */
  dbMaxPoolSize: ({
    dataSource,
    preAggregations,
  }: DataSourceOpts) => (
    get(keyByDataSource('CUBEJS_DB_MAX_POOL', dataSource, preAggregations)).asInt()
  ),

View on GitHub (pinned to 7d981676b3)

Solutions

1. Set CUBEJS_DB_NAME (or CUBEJS_DS_<DATASOURCE>_DB_NAME) — the modern replacement for CUBEJS_DATABASE.
2. Alternatively set the legacy CUBEJS_DATABASE (or CUBEJS_DS_<DATASOURCE>_DATABASE) variable.
3. Audit all dataSource values in cube.js config to ensure each has a matching env prefix.
4. Remove required: true if the caller resolves the database through other means.

Example fix

// before
CUBEJS_DATABASE=my_db   # deprecated
// after
CUBEJS_DB_NAME=my_db

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

try {
  const database = getEnv('database', { dataSource, required: true });
} catch (e) {
  if (String(e.message).includes('CUBEJS_DATABASE') && e.message.includes('required and missing')) {
    console.error('Set CUBEJS_DB_NAME (modern replacement for CUBEJS_DATABASE)');
    process.exit(1);
  }
  throw e;
}

When it happens

Trigger: Calling the database accessor with required: true while neither CUBEJS_DATABASE nor CUBEJS_DS_<DATASOURCE>_DATABASE is set in the environment.

Common situations: Old BigQuery/Postgres setups using CUBEJS_DATABASE before the rename to CUBEJS_DB_NAME; partial env migrations where some data sources got new names and others didn't; forgotten DS-prefixed override.

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_DB_NAME', dataSource)} is requ
• 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/ea3c62cbfb896add. Report an issue: GitHub.