Configuration file must export the configuration as default.

Error message

Configuration file must export the configuration as default.

What it means

Cube read the configuration file from disk (require of cube.js / dist config) and the module's export did not contain a `default` property holding CreateOptions. loadConfigurationFromFile only accepts `file.default`. Practically the config must be exported as default (ESM style or module.exports.default).

Source

Thrown at packages/cubejs-server/src/server/container.ts:370

    });

    return config as any;
  }

  protected async loadConfigurationFromFile(): Promise<CreateOptions> {
    const file = await import(
      path.join(process.cwd(), 'cube.js')
    );

    if (this.configuration.debug) {
      console.log('Loaded js configuration file', file);
    }

    if (file.default) {
      return file.default;
    }

    throw new Error(
      'Configuration file must export the configuration as default.'
    );
  }

  /**
   * @param embedded Cube.js will start without https/ws/graceful shutdown + without timers
   */
  public async start(embedded: boolean = false) {
    const makeInstance = async (override: boolean) => {
      const userConfig = await this.lookupConfiguration(override);

      const configuration = {
        // By default graceful shutdown is disabled, but this value is needed for reboot
        gracefulShutdown: getEnv('gracefulShutdown') || (process.env.NODE_ENV === 'production' ? 30 : 2),
        ...userConfig,
      };

      const server = await this.runServerInstance(

View on GitHub (pinned to 7d981676b3)

Solutions

Export the config as default: `module.exports.default = { ... }` or `export default { ... }` in TS
Migrate legacy `module.exports = {...}` configs to the default-export form
Enable esModuleInterop in tsconfig if compiling TS config manually
Confirm which file lookupConfiguration is loading (cube.js vs dist/cube.js) and fix the right one

Example fix

// before
module.exports = {
  driverFactory: () => new PostgresDriver({}),
};

// after
module.exports = {
  default: {
    driverFactory: () => new PostgresDriver({}),
  },
};
// or in TS/ESM: export default { driverFactory: ... };

Defensive patterns

Strategy: validation

Validate before calling

const configModule = require('./cube.js');
if (!configModule.default) {
  throw new Error('cube.js must export configuration as default: module.exports.default = {...}');
}

Type guard

function hasDefaultExport(m: unknown): m is { default: Record<string, unknown> } {
  return typeof m === 'object' && m !== null && 'default' in m;
}

Try / catch

try {
  await server.listen();
} catch (e) {
  if (e.message === 'Configuration file must export the configuration as default.') {
    console.error('Convert module.exports = {...} to module.exports.default = {...} or export default');
  }
  throw e;
}

Prevention

Migrate legacy cube.js configs to the default-export form
Grep the project for `module.exports =` in config files after upgrading Cube
Use TypeScript configs (which enforce export default) going forward
Run the server locally before deploying to catch config loading issues

When it happens

Trigger: A cube.js config using `module.exports = { ... }` without a default key, or named-only exports, being loaded by loadConfigurationFromFile via lookupConfiguration.

Common situations: Older Cube projects (pre-default-export era) upgrading the server package; copying config snippets using module.exports into a project whose loader expects default export; TypeScript files compiled without proper interop so default lands elsewhere.

Related errors

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