{"id":"84aff9fa1d1db088","repo":"drizzle-team/drizzle-orm","slug":"you-need-to-specify-mode-planetscale-or-defa","errorCode":null,"errorMessage":"You need to specify \"mode\": \"planetscale\" or \"default\" when providing a schema. Read more: https://orm.drizzle.team/docs/rqb#modes","messagePattern":"You need to specify \"mode\": \"planetscale\" or \"default\" when providing a schema\\. Read more: https://orm\\.drizzle\\.team/docs/rqb#modes","errorType":"exception","errorClass":"DrizzleError","httpStatus":null,"severity":"error","filePath":"drizzle-orm/src/mysql2/driver.ts","lineNumber":82,"sourceCode":"\tclient: TClient,\n\tconfig: MySql2DrizzleConfig<TSchema> = {},\n): MySql2Database<TSchema> & {\n\t$client: AnyMySql2Connection extends TClient ? CallbackPool : TClient;\n} {\n\tconst dialect = new MySqlDialect({ casing: config.casing });\n\tlet logger;\n\tif (config.logger === true) {\n\t\tlogger = new DefaultLogger();\n\t} else if (config.logger !== false) {\n\t\tlogger = config.logger;\n\t}\n\n\tconst clientForInstance = isCallbackClient(client) ? client.promise() : client;\n\n\tlet schema: RelationalSchemaConfig<TablesRelationalConfig> | undefined;\n\tif (config.schema) {\n\t\tif (config.mode === undefined) {\n\t\t\tthrow new DrizzleError({\n\t\t\t\tmessage:\n\t\t\t\t\t'You need to specify \"mode\": \"planetscale\" or \"default\" when providing a schema. Read more: https://orm.drizzle.team/docs/rqb#modes',\n\t\t\t});\n\t\t}\n\n\t\tconst tablesConfig = extractTablesRelationalConfig(\n\t\t\tconfig.schema,\n\t\t\tcreateTableRelationsHelpers,\n\t\t);\n\t\tschema = {\n\t\t\tfullSchema: config.schema,\n\t\t\tschema: tablesConfig.tables,\n\t\t\ttableNamesMap: tablesConfig.tableNamesMap,\n\t\t};\n\t}\n\n\tconst mode = config.mode ?? 'default';\n","sourceCodeStart":64,"sourceCodeEnd":100,"githubUrl":"https://github.com/drizzle-team/drizzle-orm/blob/b7862528fd8fc39bc2653a6c18dad7c1f4e68d10/drizzle-orm/src/mysql2/driver.ts#L64-L100","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nimport { drizzle } from 'drizzle-orm/mysql2';\nconst db = drizzle(pool, { schema }); // throws: mode required\n\n// after\nconst db = drizzle(pool, { schema, mode: 'default' });","handlingStrategy":"validation","validationCode":"import type { MySql2DrizzleConfig } from 'drizzle-orm/mysql2';\n\nfunction assertValidMysqlConfig<T extends Record<string, unknown>>(\n  config: MySql2DrizzleConfig<T>,\n): void {\n  if (config.schema && !config.mode) {\n    throw new Error('Provide mode: \"default\" | \"planetscale\" when passing schema to mysql2 drizzle().');\n  }\n}\n\nassertValidMysqlConfig(config);","typeGuard":"function hasSchemaAndMode(c: any): c is { schema: unknown; mode: 'default' | 'planetscale' } {\n  return c && typeof c.schema !== 'undefined' && (c.mode === 'default' || c.mode === 'planetscale');\n}","tryCatchPattern":null,"preventionTips":["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."],"tags":["mysql","mysql2","config","schema","planetscale"],"analyzedSha":"b7862528fd8fc39bc2653a6c18dad7c1f4e68d10","analyzedAt":"2026-08-03T18:11:14.318Z","schemaVersion":2}