externalDriverFactory is not provided. Please use CUBEJS_DEV

Error message

externalDriverFactory is not provided. Please use CUBEJS_DEV_MODE=true or provide Cube Store connection env variables for production usage.

What it means

PreAggregationLoadCache.fetchTables handles pre-aggregations marked external (stored in Cube Store / external DB). If preAggregation.external is true but no externalDriverFactory was supplied to the orchestrator, it throws because there is no driver to query the external store. The message points to CUBEJS_DEV_MODE or Cube Store connection env variables.

Source

Thrown at packages/cubejs-query-orchestrator/src/orchestrator/PreAggregationLoadCache.ts:84

  protected async tablesFromCache(preAggregation, forceRenew: boolean = false) {
    let tables = forceRenew ? null : await this.queryCache.getCacheDriver().get(this.tablesCachePrefixKey(preAggregation));
    if (!tables) {
      tables = await this.preAggregations.getLoadCacheQueue(this.dataSource).executeInQueue(
        'query',
        `Fetch tables for ${preAggregation.preAggregationsSchema}`,
        {
          preAggregation, requestId: this.requestId
        },
        0,
        { requestId: this.requestId }
      );
    }
    return tables;
  }

  public async fetchTables(preAggregation: PreAggregationDescription) {
    if (preAggregation.external && !this.externalDriverFactory) {
      throw new Error('externalDriverFactory is not provided. Please use CUBEJS_DEV_MODE=true or provide Cube Store connection env variables for production usage.');
    }

    const newTables = await this.fetchTablesNoCache(preAggregation);
    await this.queryCache.getCacheDriver().set(
      this.tablesCachePrefixKey(preAggregation),
      newTables,
      this.preAggregations.options.preAggregationsSchemaCacheExpire || 60 * 60
    );
    return newTables;
  }

  private async fetchTablesNoCache(preAggregation: PreAggregationDescription) {
    const client = preAggregation.external ?
      await this.externalDriverFactory() :
      await this.driverFactory();

    if (this.tablePrefixes && client.getPrefixTablesQuery && this.preAggregations.options.skipExternalCacheAndQueue) {
      return client.getPrefixTablesQuery(preAggregation.preAggregationsSchema, this.tablePrefixes);

View on GitHub (pinned to 7d981676b3)

Solutions

Set CUBEJS_DEV_MODE=true for local development (uses in-process Cube Store handling)
Provide Cube Store connection env variables (CUBEJS_CUBE_STORE_HOST/PORT/etc.) so the external driver factory is created
If constructing the orchestrator manually, pass an externalDriverFactory option

Example fix

// before (.env, production)
# no Cube Store config
// after (.env, production)
CUBEJS_CUBE_STORE_HOST=cubestore
CUBEJS_CUBE_STORE_PORT=3030

Defensive patterns

Strategy: validation

Validate before calling

const hasCubeStore = process.env.CUBEJS_CUBE_STORE_HOST && process.env.CUBEJS_CUBE_STORE_PORT;
if (!hasCubeStore && process.env.CUBEJS_DEV_MODE !== 'true') {
  throw new Error('Configure Cube Store env vars or set CUBEJS_DEV_MODE=true for external pre-aggregations');
}

Type guard

const externalReady = (orchestrator) => !!orchestrator?.preAggregations?.options?.externalDriverFactory || !!orchestrator?.externalDriverFactory;

Try / catch

try {
  await loadCache.fetchTables(preAggregation);
} catch (e) {
  if (String(e.message).includes('externalDriverFactory is not provided')) {
    console.error('Provide Cube Store env vars or an externalDriverFactory option');
  }
  throw e;
}

Prevention

Set Cube Store connection env vars in all non-dev environments
When constructing the orchestrator manually, always pass externalDriverFactory if external rollups are used
Add a startup health check verifying Cube Store connectivity

When it happens

Trigger: A query requiring an external (rolled-up to Cube Store) pre-aggregation executes while the orchestrator was constructed without externalDriverFactory — e.g. Cube Store connection env vars (CUBEJS_CUBE_STORE_*) absent and dev mode off.

Common situations: Production deployments missing Cube Store env configuration; custom orchestrator usage that forgot to pass externalDriverFactory; enabling external rollups in an environment where only the DB driver is configured.

Related errors

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