Invalid cube-server-core options: ${error.message || error.t

Error message

Invalid cube-server-core options: ${error.message || error.toString()}

What it means

validateOptions runs the Cube server-core options object through a Joi schema (schemaOptions). If any option fails validation, it aggregates the Joi error messages and throws 'Invalid cube-server-core options: ...'. This catches wrong option types and unknown/invalid values early at server construction.

Source

Thrown at packages/cubejs-server-core/src/core/optionsValidate.ts:166

  sqlPort: Joi.number(),
  pgSqlPort: Joi.number(),
  gatewayPort: Joi.number(),
  sqlSuperUser: Joi.string(),
  checkSqlAuth: Joi.func(),
  canSwitchSqlUser: Joi.func(),
  sqlUser: Joi.string(),
  sqlPassword: Joi.string(),
  semanticLayerSync: Joi.func(),
  // Additional system flags
  serverless: Joi.boolean(),
  allowNodeRequire: Joi.boolean(),
  fastReload: Joi.boolean(),
});

export function validateOptions<T>(options: T): T {
  const { error, value } = schemaOptions.validate(options, { abortEarly: false });
  if (error) {
    throw new Error(`Invalid cube-server-core options: ${error.message || error.toString()}`);
  }

  return value;
}

View on GitHub (pinned to 7d981676b3)

Solutions

Read the Joi error message appended to the error — it names the exact offending option and expected type
Fix the option type/value in the server config to match the schema (booleans for flags, correct numeric ranges, etc.)
Remove unknown/obsolete options or move them to the correct nested object
Pin/align your config with the schema in packages/cubejs-server-core/src/core/optionsValidate.ts for your Cube version

Example fix

// before
new CubeServer({
  dbType: 'postgres',
  scheduledRefresh: 'yes'
});
// after
new CubeServer({
  dbType: 'postgres',
  scheduledRefresh: true
});

Defensive patterns

Strategy: validation

Validate before calling

import { validateOptions } from './core/optionsValidate';
try { validateOptions(myOptions); } catch (e) { console.error(e.message); process.exit(1); }

Try / catch

try {
  const server = new CubeServer(options);
} catch (e) {
  if (e.message.startsWith('Invalid cube-server-core options:')) {
    console.error('Config error:', e.message); process.exit(1);
  } else { throw e; }
}

Prevention

Read the Joi message appended to the error for the exact offending option
Validate config against the schema at CI/startup time
Use typed config objects matching the Cube version's option types
Remove obsolete options when upgrading Cube

When it happens

Trigger: Constructing CubeServer/CubeCore with an options object where any key violates the Joi schema — e.g. wrong type (string instead of boolean), unexpected value format — and validateOptions() is invoked via validated().

Common situations: Typos in option names or values; passing environment-derived strings ('true'/'false') where booleans are expected; upgrading Cube and using options that changed shape; passing driver-specific options at the wrong nesting level.

Related errors

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