{"id":"864d15d525c37f84","repo":"drizzle-team/drizzle-orm","slug":"failed-query-querystring-params-params","errorCode":null,"errorMessage":"Failed query: ${queryString}\nparams: ${params}","messagePattern":"Failed query: (.+?)\nparams: (.+?)","errorType":"exception","errorClass":"DrizzleQueryError","httpStatus":null,"severity":"error","filePath":"drizzle-orm/src/pg-core/session.ts","lineNumber":73,"sourceCode":"\t\treturn this;\n\t}\n\n\tstatic readonly [entityKind]: string = 'PgPreparedQuery';\n\n\t/** @internal */\n\tjoinsNotNullableMap?: Record<string, boolean>;\n\n\t/** @internal */\n\tprotected async queryWithCache<T>(\n\t\tqueryString: string,\n\t\tparams: any[],\n\t\tquery: () => Promise<T>,\n\t): Promise<T> {\n\t\tif (this.cache === undefined || is(this.cache, NoopCache) || this.queryMetadata === undefined) {\n\t\t\ttry {\n\t\t\t\treturn await query();\n\t\t\t} catch (e) {\n\t\t\t\tthrow new DrizzleQueryError(queryString, params, e as Error);\n\t\t\t}\n\t\t}\n\n\t\t// don't do any mutations, if globally is false\n\t\tif (this.cacheConfig && !this.cacheConfig.enable) {\n\t\t\ttry {\n\t\t\t\treturn await query();\n\t\t\t} catch (e) {\n\t\t\t\tthrow new DrizzleQueryError(queryString, params, e as Error);\n\t\t\t}\n\t\t}\n\n\t\t// For mutate queries, we should query the database, wait for a response, and then perform invalidation\n\t\tif (\n\t\t\t(\n\t\t\t\tthis.queryMetadata.type === 'insert' || this.queryMetadata.type === 'update'\n\t\t\t\t|| this.queryMetadata.type === 'delete'\n\t\t\t) && this.queryMetadata.tables.length > 0","sourceCodeStart":55,"sourceCodeEnd":91,"githubUrl":"https://github.com/drizzle-team/drizzle-orm/blob/b7862528fd8fc39bc2653a6c18dad7c1f4e68d10/drizzle-orm/src/pg-core/session.ts#L55-L91","documentation":"PgPreparedQuery.queryWithCache (session.ts:70-74) wraps the underlying driver query in a try/catch for the no-cache path (cache is undefined, NoopCache, or queryMetadata is undefined). When the driver rejects — constraint violation, syntax error, type mismatch, connection drop, etc. — it is re-thrown as a DrizzleQueryError carrying the rendered SQL string and bound params, with the original error on .cause.","triggerScenarios":"Any executed query that the Postgres server rejects: unique/foreign-key/check constraint violations, NOT NULL failures, undefined_column, invalid input syntax, division by zero, lock contention timeouts, or driver-level connection errors — occurring when caching is not configured.","commonSituations":"Inserting a duplicate key; violating a foreign key; passing a malformed value (e.g., bad date/UUID); connection pool exhausted mid-query; permission denied for role; transaction aborted by a prior statement.","solutions":["Read .cause on the DrizzleQueryError to get the original Postgres error code (e.g., 23505 unique_violation).","Fix the offending data/constraint based on the Postgres SQLSTATE in the cause.","For connection/timeout causes, tune pool size and statement timeouts.","Log the queryString and params (redacted) from the error for debugging."],"exampleFix":"// before\nawait db.insert(users).values({ email: 'dup@example.com' }); // 23505 unique_violation\n\n// after\ntry {\n  await db.insert(users).values({ email: 'dup@example.com' });\n} catch (e) {\n  if (e instanceof DrizzleQueryError && (e.cause as any)?.code === '23505') {\n    // handle duplicate\n  } else throw e;\n}","handlingStrategy":"try-catch","validationCode":"// Validate inputs before sending to avoid common server rejections.\nfunction assertInsertable(row: Record<string, unknown>, required: string[]) {\n  for (const col of required) {\n    if (row[col] === undefined || row[col] === null) {\n      throw new Error(`Missing required column: ${col}`);\n    }\n  }\n}","typeGuard":"import { DrizzleQueryError } from 'drizzle-orm';\n\nfunction isPgError(e: unknown, code?: string): e is DrizzleQueryError {\n  return e instanceof DrizzleQueryError\n    && (code ? (e.cause as any)?.code === code : true);\n}","tryCatchPattern":"import { DrizzleQueryError } from 'drizzle-orm';\n\ntry {\n  await db.insert(users).values(row);\n} catch (e) {\n  if (e instanceof DrizzleQueryError) {\n    const pg = e.cause as { code?: string; message?: string } | undefined;\n    if (pg?.code === '23505') { /* unique violation */ }\n    else if (pg?.code === '23503') { /* foreign key */ }\n    else throw e;\n  } else throw e;\n}","preventionTips":["Always inspect .cause.code (Postgres SQLSTATE) to branch handling.","Validate required fields and types before inserting.","Keep pool size and statement timeouts sized to load."],"tags":["runtime","driver","query-error","postgres"],"analyzedSha":"b7862528fd8fc39bc2653a6c18dad7c1f4e68d10","analyzedAt":"2026-08-03T18:11:14.318Z","schemaVersion":2}