cube-js/cube · error · Error

The ${keyByDataSource('CUBEJS_DB_SCHEMA', dataSource)} is re

Error message

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

What it means

cubejsDbSchema reads CUBEJS_DB_SCHEMA (per data source) and, when required: true is passed and the variable is unset/empty, throws an error naming the resolved variable. CUBEJS_DB_SCHEMA is deprecated in favor of CUBEJS_DB_NAME, so hitting this usually signals legacy configuration.

Source

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

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

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

View on GitHub (pinned to 7d981676b3)

Solutions

1. Migrate to CUBEJS_DB_NAME (or CUBEJS_DS_<DATASOURCE>_DB_NAME), as the schema variable is deprecated.
2. If you must keep it, set CUBEJS_DB_SCHEMA (or CUBEJS_DS_<DATASOURCE>_DB_SCHEMA) to the schema/database name.
3. Search your deployment manifests for CUBEJS_DB_SCHEMA and reconcile naming with the dataSource passed in code.
4. Remove required: true if the schema is optional for your driver.

Example fix

// before
CUBEJS_DB_SCHEMA=public   # deprecated, may still throw if missing per DS
// after
CUBEJS_DB_NAME=analytics

if (process.env.CUBEJS_DB_SCHEMA !== undefined) {
  console.warn('CUBEJS_DB_SCHEMA is deprecated; use CUBEJS_DB_NAME instead');
}
const dsKey = `CUBEJS_DS_${dataSource.toUpperCase()}_DB_SCHEMA`;
if (!process.env[dsKey] && !process.env.CUBEJS_DB_SCHEMA && !process.env.CUBEJS_DB_NAME)
  throw new Error(`Set CUBEJS_DB_NAME for data source ${dataSource}`);

try {
  const schema = getEnv('dbSchema', { dataSource, required: true });
} catch (e) {
  if (String(e.message).includes('DB_SCHEMA') && e.message.includes('required and missing')) {
    console.error('Migrate to CUBEJS_DB_NAME; CUBEJS_DB_SCHEMA is deprecated');
  }
  throw e;
}

When it happens

Trigger: Calling the schema accessor with required: true while neither CUBEJS_DB_SCHEMA nor CUBEJS_DS_<DATASOURCE>_DB_SCHEMA is set; often after Cube logs the deprecation warning pointing to CUBEJS_DB_NAME.

Common situations: Older Cube configs still using CUBEJS_DB_SCHEMA after upgrade; teams renaming vars but leaving required checks; per-data-source setups missing the DS-prefixed schema var.

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_DATABASE', dataSource)} is req
• 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/02fb2bccacad6a01. Report an issue: GitHub.