drizzle-team/drizzle-orm · error · DrizzleError

You need to specify "mode": "planetscale" or "default" when

Error message

You need to specify "mode": "planetscale" or "default" when providing a schema. Read more: https://orm.drizzle.team/docs/rqb#modes

What it means

A DrizzleError thrown by the mysql2 drizzle() factory (drizzle-orm/src/mysql2/driver.ts:82) when the caller passes a schema but omits mode. Drizzle needs to know whether to target PlanetScale (which lacks certain MySQL features) or standard MySQL before it can build the relational query schema, so providing schema without mode is ambiguous and rejected at construction time.

Source

Thrown at drizzle-orm/src/mysql2/driver.ts:82

	client: TClient,
	config: MySql2DrizzleConfig<TSchema> = {},
): MySql2Database<TSchema> & {
	$client: AnyMySql2Connection extends TClient ? CallbackPool : TClient;
} {
	const dialect = new MySqlDialect({ casing: config.casing });
	let logger;
	if (config.logger === true) {
		logger = new DefaultLogger();
	} else if (config.logger !== false) {
		logger = config.logger;
	}

	const clientForInstance = isCallbackClient(client) ? client.promise() : client;

	let schema: RelationalSchemaConfig<TablesRelationalConfig> | undefined;
	if (config.schema) {
		if (config.mode === undefined) {
			throw new DrizzleError({
				message:
					'You need to specify "mode": "planetscale" or "default" when providing a schema. Read more: https://orm.drizzle.team/docs/rqb#modes',
			});
		}

		const tablesConfig = extractTablesRelationalConfig(
			config.schema,
			createTableRelationsHelpers,
		);
		schema = {
			fullSchema: config.schema,
			schema: tablesConfig.tables,
			tableNamesMap: tablesConfig.tableNamesMap,
		};
	}

	const mode = config.mode ?? 'default';

View on GitHub (pinned to b7862528fd)

Solutions

Add mode: 'default' for standard MySQL (mysql2 driver) or mode: 'planetscale' when targeting PlanetScale.
If you did not mean to use the relational query API, remove the schema option.
Re-check the example at https://orm.drizzle.team/docs/rqb#modes for your target.

Example fix

// before
import { drizzle } from 'drizzle-orm/mysql2';
const db = drizzle(pool, { schema }); // throws: mode required

// after
const db = drizzle(pool, { schema, mode: 'default' });

Defensive patterns

Strategy: validation

Validate before calling

import type { MySql2DrizzleConfig } from 'drizzle-orm/mysql2';

function assertValidMysqlConfig<T extends Record<string, unknown>>(
  config: MySql2DrizzleConfig<T>,
): void {
  if (config.schema && !config.mode) {
    throw new Error('Provide mode: "default" | "planetscale" when passing schema to mysql2 drizzle().');
  }
}

assertValidMysqlConfig(config);

Type guard

function hasSchemaAndMode(c: any): c is { schema: unknown; mode: 'default' | 'planetscale' } {
  return c && typeof c.schema !== 'undefined' && (c.mode === 'default' || c.mode === 'planetscale');
}

Prevention

Always pair schema with mode in mysql2 config.
Centralise drizzle() construction behind a helper that enforces the schema+mode rule.
If you do not need the relational query API, omit schema entirely.

When it happens

Trigger: Calling drizzle(client, { schema, ... }) or drizzle({ connection, schema }) from drizzle-orm/mysql2 without a mode field. The construct() helper checks config.schema truthy and config.mode undefined and throws before any DB connection is made.

Common situations: Copy-pasting a config from a Postgres or a non-schema Drizzle setup, upgrading from an older Drizzle version that did not require mode, or following a tutorial that omitted mode. The error message itself points to the docs.

Related errors

AI-assisted analysis of drizzle-team/drizzle-orm@b7862528fd (2026-08-03). Data as JSON: /data/errors/84aff9fa1d1db088.json. Report an issue: GitHub.