cube-js/cube · error · Error

Either CUBEJS_DB_TYPE or CreateOptions.driverFactory must be

Error message

Either CUBEJS_DB_TYPE or CreateOptions.driverFactory must be specified

What it means

sanitizeOptions requires the database type to be discoverable in production mode: either the CUBEJS_DB_TYPE environment variable is set or a CreateOptions.driverFactory is provided. If neither is present (and dev mode is off), startup fails because Cube cannot determine which driver to instantiate. In dev mode this check is skipped because the Playground can supply the type later.

Source

Thrown at packages/cubejs-server-core/src/core/OptsHandler.ts:83

      throw new Error(
        'CreateOptions.dbType was removed in v1.7.0. ' +
        'Use driverFactory instead (return a DriverConfig `{ type, ... }`), ' +
        'or set the CUBEJS_DB_TYPE environment variable. ' +
        'See https://github.com/cube-js/cube/blob/master/DEPRECATION.md#dbtype'
      );
    }

    const validated = validateOptions(opts);

    // Probed for its throw: the only consumer is per-request code (normalizeQuery)
    getEnv('defaultTimezone');

    if (
      !this.isDevMode() &&
      !process.env.CUBEJS_DB_TYPE &&
      !opts.driverFactory
    ) {
      throw new Error(
        'Either CUBEJS_DB_TYPE or CreateOptions.driverFactory must be specified'
      );
    }

    return validated;
  }

  /**
   * Assert value returned from the driver factory.
   */
  private assertDriverFactoryResult(
    val: DriverConfig | BaseDriver,
  ) {
    if (isDriver(val)) {
      if (!this.driverFactoryType) {
        this.driverFactoryType = 'BaseDriver';
      } else if (this.driverFactoryType !== 'BaseDriver') {
        throw new Error(

View on GitHub (pinned to 7d981676b3)

Solutions

Set CUBEJS_DB_TYPE in the environment (e.g. postgres, mysql)
Or pass driverFactory to create(): driverFactory: async () => ({ type: 'postgres', ... })
Verify the env file is actually loaded in the deployment environment
In dev mode, pick the db type in the Playground so it gets persisted

Example fix

// before
create({ apiSecret: 'secret' }) // prod, no env
// after
create({ apiSecret: 'secret', driverFactory: async () => ({ type: 'postgres' }) })
// or: CUBEJS_DB_TYPE=postgres in the environment

Defensive patterns

Strategy: validation

Validate before calling

function assertDbTypeConfigured(opts) {
  const devMode = process.env.CUBEJS_DEV_MODE === 'true';
  if (!devMode && !process.env.CUBEJS_DB_TYPE && typeof opts.driverFactory !== 'function') {
    throw new Error('Set CUBEJS_DB_TYPE or provide CreateOptions.driverFactory before starting Cube in production');
  }
}
assertDbTypeConfigured(myCreateOptions);

Type guard

function hasDbTypeSource(opts) {
  return typeof opts.driverFactory === 'function' || !!process.env.CUBEJS_DB_TYPE;
}

Try / catch

try {
  const server = await create(opts);
} catch (e) {
  if (e.message.includes('Either CUBEJS_DB_TYPE or CreateOptions.driverFactory')) {
    console.error('Deployment misconfigured: no database type source. Check env files / docker env.');
  }
  throw e;
}

Prevention

Set CUBEJS_DB_TYPE in every deployment environment (docker-compose, k8s manifests, CI)
Remember dev mode skips this check — always test with production-like env before deploys
Prefer an explicit driverFactory for programmatic setups so the config is in code
Include a startup config lint step in CI that verifies required env vars

When it happens

Trigger: Running cubejs-server-core with CUBEJS_DEV_MODE unset/false, no CUBEJS_DB_TYPE in the environment, and no driverFactory passed to create(). E.g. deploying to production with only CUBEJS_DB_HOST/CUBEJS_DB_NAME set.

Common situations: Production deploys where .env wasn't copied; docker images missing CUBEJS_DB_TYPE; code that worked in dev mode (where the check is skipped) failing in prod; multi-data-source setups forgetting CUBEJS_DS_<ds>_DB_TYPE for the default source.

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/37e4364cfdd9795e. Report an issue: GitHub.