{"id":"7e6f2e0d2403b53f","repo":"drizzle-team/drizzle-orm","slug":"warning-you-need-to-pass-an-instance-of-client","errorCode":null,"errorMessage":"Warning: You need to pass an instance of Client:\n\nimport { Client } from \"@planetscale/database\";\n\nconst client = new Client({\n  host: process.env[\"DATABASE_HOST\"],\n  username: process.env[\"DATABASE_USERNAME\"],\n  password: process.env[\"DATABASE_PASSWORD\"],\n});\n\nconst db = drizzle(client);\n\t\t","messagePattern":"Warning: You need to pass an instance of Client:\n\nimport (.+?) from \"@planetscale/database\";\n\nconst client = new Client\\((.+?)\\);\n\nconst db = drizzle\\(client\\);\n\t\t","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"drizzle-orm/src/planetscale-serverless/driver.ts","lineNumber":41,"sourceCode":"export class PlanetScaleDatabase<\n\tTSchema extends Record<string, unknown> = Record<string, never>,\n> extends MySqlDatabase<PlanetscaleQueryResultHKT, PlanetScalePreparedQueryHKT, TSchema> {\n\tstatic override readonly [entityKind]: string = 'PlanetScaleDatabase';\n}\n\nfunction construct<\n\tTSchema extends Record<string, unknown> = Record<string, never>,\n\tTClient extends Client = Client,\n>(\n\tclient: TClient,\n\tconfig: DrizzleConfig<TSchema> = {},\n): PlanetScaleDatabase<TSchema> & {\n\t$client: TClient;\n} {\n\t// Client is not Drizzle Object, so we can ignore this rule here\n\t// eslint-disable-next-line no-instanceof/no-instanceof\n\tif (!(client instanceof Client)) {\n\t\tthrow new Error(`Warning: You need to pass an instance of Client:\n\nimport { Client } from \"@planetscale/database\";\n\nconst client = new Client({\n  host: process.env[\"DATABASE_HOST\"],\n  username: process.env[\"DATABASE_USERNAME\"],\n  password: process.env[\"DATABASE_PASSWORD\"],\n});\n\nconst db = drizzle(client);\n\t\t`);\n\t}\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) {","sourceCodeStart":23,"sourceCodeEnd":59,"githubUrl":"https://github.com/drizzle-team/drizzle-orm/blob/b7862528fd8fc39bc2653a6c18dad7c1f4e68d10/drizzle-orm/src/planetscale-serverless/driver.ts#L23-L59","documentation":"The PlanetScale serverless driver's construct() function guards that the first argument to drizzle() is an actual instance of @planetscale/database Client (checked via `instanceof Client`). Passing a config object, a fetcher, a connection URL string, or any other value fails the instanceof check and throws this descriptive error. The message itself is the fix template showing how to construct the Client correctly.","triggerScenarios":"Calling drizzle(configObject) instead of drizzle(new Client(configObject)). Passing process.env.DATABASE_URL or a raw {host,username,password} object. Importing Client from the wrong package or a mock Client in tests. Version mismatch where @planetscale/database exports a different Client class than the one Drizzle imports.","commonSituations":"Copy-paste from MySQL/Postgres examples where drizzle() accepts a connection URL. Using a singleton Client across Drizzle and raw PlanetScale queries but wrapping it incorrectly. Upgrading @planetscale/database to a version with a changed Client shape, or duplicate installations causing two Client classes.","solutions":["Construct the Client first, then pass it: const client = new Client({host, username, password}); const db = drizzle(client);","Verify there is only one copy of @planetscale/database installed (check npm ls @planetscale/database / pnpm why) so instanceof resolves to the same class.","In tests, use the real Client with a mock fetcher rather than a plain object stub, or use Drizzle's schema/dialect test helpers without the driver wrapper.","Confirm you imported drizzle from drizzle-orm/planetscale-serverless, not another dialect entry point."],"exampleFix":"// before (throws: config object is not a Client instance)\nimport { drizzle } from 'drizzle-orm/planetscale-serverless';\nconst db = drizzle({\n  host: process.env.DATABASE_HOST,\n  username: process.env.DATABASE_USERNAME,\n  password: process.env.DATABASE_PASSWORD,\n});\n\n// after\nimport { Client } from '@planetscale/database';\nimport { drizzle } from 'drizzle-orm/planetscale-serverless';\nconst client = new Client({\n  host: process.env.DATABASE_HOST,\n  username: process.env.DATABASE_USERNAME,\n  password: process.env.DATABASE_PASSWORD,\n});\nconst db = drizzle(client);","handlingStrategy":"type-guard","validationCode":"import { Client } from '@planetscale/database';\n\nfunction makeDb(client: unknown) {\n  if (!(client instanceof Client)) {\n    throw new TypeError('Expected an instance of @planetscale/database Client');\n  }\n  return drizzle(client);\n}\n\n// Usage:\nconst client = new Client({ host, username, password });\nconst db = makeDb(client);","typeGuard":"import { Client } from '@planetscale/database';\n\nfunction isPlanetScaleClient(v: unknown): v is Client {\n  return v instanceof Client;\n}\n\n// before passing to drizzle:\nif (!isPlanetScaleClient(client)) {\n  throw new Error('drizzle() needs a real Client instance, not a config object');\n}","tryCatchPattern":"try {\n  const db = drizzle(client as any);\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('Warning: You need to pass an instance of Client')) {\n    // re-construct the Client correctly and retry\n  } else throw e;\n}","preventionTips":["Always construct `new Client({...})` before calling drizzle(); never pass a config object directly.","Run `npm ls @planetscale/database` in CI to detect duplicate installs that break instanceof.","In tests, inject the real Client with a mocked fetch rather than a plain object."],"tags":["planetscale","serverless","configuration","instanceof","initialization"],"analyzedSha":"b7862528fd8fc39bc2653a6c18dad7c1f4e68d10","analyzedAt":"2026-08-03T18:11:14.318Z","schemaVersion":2}