cube-js/cube · error · Error

Unexpected CreateOptions.driverFactory result value. Must be

Error message

Unexpected CreateOptions.driverFactory result value. Must be either DriverConfig or driver instance: <${typeof val}>${JSON.stringify(val, undefined, 2)}

What it means

If the value returned by the user-supplied driverFactory is neither a driver instance (isDriver check) nor a DriverConfig object with a string `type` property, assertDriverFactoryResult throws, including the typeof and a JSON dump of the offending value. Typical culprits are undefined (async function returned nothing), a Promise-wrapped value mishandled, or an object without a string `type`.

Source

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

          'CreateOptions.driverFactory function must return either ' +
          'BaseDriver or DriverConfig.'
        );
      }
      return <BaseDriver>val;
    } else if (
      val && (<DriverConfig>val).type && typeof (<DriverConfig>val).type === 'string'
    ) {
      if (!this.driverFactoryType) {
        this.driverFactoryType = 'DriverConfig';
      } else if (this.driverFactoryType !== 'DriverConfig') {
        throw new Error(
          'CreateOptions.driverFactory function must return either ' +
          'BaseDriver or DriverConfig.'
        );
      }
      return <DriverConfig>val;
    } else {
      throw new Error(
        'Unexpected CreateOptions.driverFactory result value. Must be either ' +
        `DriverConfig or driver instance: <${
          typeof val
        }>${
          JSON.stringify(val, undefined, 2)
        }`
      );
    }
  }

  /**
   * Assert orchestration options.
   */
  private asserOrchestratorOptions(opts: OrchestratorOptions) {
    if (
      opts.rollupOnlyMode &&
      this.isApiWorker() &&
      getEnv('preAggregationsBuilder')

View on GitHub (pinned to 7d981676b3)

Solutions

1. Return an object with a string `type`, e.g. { type: 'postgres', ... }
2. Or return an actual driver instance, e.g. new PostgresDriver({...})
3. Make sure the function is async/awaited so you return the value, not a dangling Promise path
4. Inspect the JSON dump in the error to see the exact offending value

Example fix

// before
driverFactory: async () => ({ host: 'localhost' }) // missing type
// after
driverFactory: async () => ({ type: 'postgres', host: 'localhost' })

async function safeDriverFactory(ctx) {
  const val = await myDriverFactory(ctx);
  if (val == null || !(typeof val.testConnection === 'function' || typeof val.type === 'string')) {
    throw new Error(`driverFactory must return DriverConfig or driver instance, got <${typeof val}>: ${JSON.stringify(val)}`);
  }
  return val;
}

function isValidFactoryResult(val) {
  if (val == null) return false;
  if (typeof val.testConnection === 'function') return true; // BaseDriver
  return typeof (val).type === 'string'; // DriverConfig
}

try {
  await driverFactory(ctx);
} catch (e) {
  if (e.message.includes('Unexpected CreateOptions.driverFactory result value')) {
    const dump = e.message.match(/<[\s\S]*$/)[0];
    console.error('Fix factory return value:', dump);
  }
  throw e;
}

When it happens

Trigger: driverFactory: async () => { /* no return */ } (returns undefined); returning { host: '...' } without `type`; returning a non-string type like { type: 123 }; returning a class constructor instead of an instance.

Common situations: Forgetful refactors dropping the return statement; copied config objects missing `type`; dynamic type built from env that ends up empty/undefined; confusion between returning a config and returning a driver.

Related errors

• Timezone must not be empty
• ${type} is required
• CreateOptions.driverFactory function must return either Base
• ${invalidFields.join(', ')} ${invalidFields.length === 1 ? '
• Can't parse date: '${from}'

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