cube-js/cube · error · Error

The ${dataSource} data source is missing in the declared CUB

Error message

The ${dataSource} data source is missing in the declared CUBEJS_DATASOURCES.

What it means

assertDataSource verifies that a requested data source is declared in the CUBEJS_DATASOURCES env variable when multi-datasource mode is active (i.e. CUBEJS_DATASOURCES is non-empty). If the requested source is not in the declared list, Cube throws this Error. It is invoked whenever a data source is resolved (queries, driver resolution, env key building).

Source

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

 */
function isMultipleDataSources(): boolean {
  // eslint-disable-next-line no-use-before-define
  return getEnv('dataSources').length > 0;
}

/**
 * Returns the specified data source if assertions are passed, throws
 * an error otherwise.
 * @param dataSource The data source to assert.
 */
export function assertDataSource(dataSource = 'default'): string {
  if (!isMultipleDataSources()) {
    return dataSource;
    // eslint-disable-next-line no-use-before-define
  } else if (getEnv('dataSources').indexOf(dataSource) >= 0) {
    return dataSource;
  } else {
    throw new Error(
      `The ${
        dataSource
      } data source is missing in the declared CUBEJS_DATASOURCES.`
    );
  }
}

/**
 * Returns data source specific environment variable name.
 */
export function keyByDataSource(origin: string, dataSource?: string, preAggregations?: boolean): string {
  if (dataSource) assertDataSource(dataSource);

  let key: string;

  if (!isMultipleDataSources() || dataSource === 'default' || !dataSource) {
    key = origin;
  } else {

View on GitHub (pinned to 7d981676b3)

Solutions

Add the missing data source name to CUBEJS_DATASOURCES (comma-separated), matching the exact case used in the schema.
Fix the dataSource(...) name in the data model so it matches an already-declared entry.
If you do not actually use multiple data sources, remove CUBEJS_DATASOURCES so single-datasource mode is active.
Restart the Cube process after changing CUBEJS_DATASOURCES so the env is re-read.

Example fix

// before (.env)
CUBEJS_DATASOURCES=orders

// schema.js
cube('Sales', { dataSource: 'inventory', ... });

// after (.env)
CUBEJS_DATASOURCES=orders,inventory

// schema.js
cube('Sales', { dataSource: 'inventory', ... });

Defensive patterns

Strategy: validation

Validate before calling

const declared = (process.env.CUBEJS_DATASOURCES || '').split(',').map(s => s.trim()).filter(Boolean);
const used = ['orders', 'inventory']; // dataSource(...) names from your schema
const missing = used.filter(d => declared.length > 0 && !declared.includes(d));
if (missing.length) {
  throw new Error(`Data sources not declared in CUBEJS_DATASOURCES: ${missing.join(', ')}`);
}

Type guard

function isDeclaredDataSource(name: string): boolean {
  const declared = (process.env.CUBEJS_DATASOURCES || '').split(',').map(s => s.trim()).filter(Boolean);
  return declared.length === 0 || declared.includes(name);
}

Try / catch

try {
  await cubeServer.run();
} catch (e) {
  if (e.message.includes('data source is missing in the declared CUBEJS_DATASOURCES')) {
    console.error(`Add the data source to CUBEJS_DATASOURCES (exact case): ${e.message}`);
    process.exit(1);
  }
  throw e;
}

Prevention

Keep CUBEJS_DATASOURCES and schema dataSource(...) names in sync, byte-for-byte.
When adding a new data source to the schema, update CUBEJS_DATASOURCES in the same change.
Remember 'default' must be listed explicitly once CUBEJS_DATASOURCES is non-empty.
Restart Cube after changing CUBEJS_DATASOURCES; add an env pre-flight check to CI.

When it happens

Trigger: Querying or configuring a dataSource whose name does not exactly match an entry in CUBEJS_DATASOURCES, e.g. schema dataSource('postgres') while CUBEJS_DATASOURCES=orders,inventory, or passing 'default' explicitly in multi-datasource mode without declaring it.

Common situations: Case or spelling mismatches between schema dataSource() calls and CUBEJS_DATASOURCES (Postgres vs postgres); renaming a data source in the schema without updating CUBEJS_DATASOURCES; forgetting to add a newly introduced data source to the env list; relying on the implicit 'default' source while multi-datasource mode is on.

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

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