{"record":{"id":"030ff3dcfbf6445d","repo":"cube-js/cube","slug":"unexpected-createoptions-driverfactory-result-valu","errorCode":null,"errorMessage":"Unexpected CreateOptions.driverFactory result value. Must be either DriverConfig or driver instance: <${typeof val}>${JSON.stringify(val, undefined, 2)}","messagePattern":"Unexpected CreateOptions\\.driverFactory result value\\. Must be either DriverConfig or driver instance: <(.+?)>(.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cubejs-server-core/src/core/OptsHandler.ts","lineNumber":120,"sourceCode":"          'CreateOptions.driverFactory function must return either ' +\n          'BaseDriver or DriverConfig.'\n        );\n      }\n      return <BaseDriver>val;\n    } else if (\n      val && (<DriverConfig>val).type && typeof (<DriverConfig>val).type === 'string'\n    ) {\n      if (!this.driverFactoryType) {\n        this.driverFactoryType = 'DriverConfig';\n      } else if (this.driverFactoryType !== 'DriverConfig') {\n        throw new Error(\n          'CreateOptions.driverFactory function must return either ' +\n          'BaseDriver or DriverConfig.'\n        );\n      }\n      return <DriverConfig>val;\n    } else {\n      throw new Error(\n        'Unexpected CreateOptions.driverFactory result value. Must be either ' +\n        `DriverConfig or driver instance: <${\n          typeof val\n        }>${\n          JSON.stringify(val, undefined, 2)\n        }`\n      );\n    }\n  }\n\n  /**\n   * Assert orchestration options.\n   */\n  private asserOrchestratorOptions(opts: OrchestratorOptions) {\n    if (\n      opts.rollupOnlyMode &&\n      this.isApiWorker() &&\n      getEnv('preAggregationsBuilder')","sourceCodeStart":102,"sourceCodeEnd":138,"githubUrl":"https://github.com/cube-js/cube/blob/7d981676b36392fec34088b9afab6bdcad40207c/packages/cubejs-server-core/src/core/OptsHandler.ts#L102-L138","documentation":"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`.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Return an object with a string `type`, e.g. { type: 'postgres', ... }","Or return an actual driver instance, e.g. new PostgresDriver({...})","Make sure the function is async/awaited so you return the value, not a dangling Promise path","Inspect the JSON dump in the error to see the exact offending value"],"exampleFix":"// before\ndriverFactory: async () => ({ host: 'localhost' }) // missing type\n// after\ndriverFactory: async () => ({ type: 'postgres', host: 'localhost' })","handlingStrategy":"validation","validationCode":"async function safeDriverFactory(ctx) {\n  const val = await myDriverFactory(ctx);\n  if (val == null || !(typeof val.testConnection === 'function' || typeof val.type === 'string')) {\n    throw new Error(`driverFactory must return DriverConfig or driver instance, got <${typeof val}>: ${JSON.stringify(val)}`);\n  }\n  return val;\n}","typeGuard":"function isValidFactoryResult(val) {\n  if (val == null) return false;\n  if (typeof val.testConnection === 'function') return true; // BaseDriver\n  return typeof (val).type === 'string'; // DriverConfig\n}","tryCatchPattern":"try {\n  await driverFactory(ctx);\n} catch (e) {\n  if (e.message.includes('Unexpected CreateOptions.driverFactory result value')) {\n    const dump = e.message.match(/<[\\s\\S]*$/)[0];\n    console.error('Fix factory return value:', dump);\n  }\n  throw e;\n}","preventionTips":["Always `return` a value from the (async) factory — an implicit undefined triggers this","Ensure DriverConfig objects include a string `type` field","Return driver instances, not classes or Promises left un-awaited","Log the factory result once at startup to catch shape regressions early"],"tags":["driver-factory","type-error","config","validation"],"backgroundTag":"invalid-driver-factory-return","analyzedSha":"7d981676b36392fec34088b9afab6bdcad40207c","analyzedAt":"2026-09-02T03:45:10.400Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}