Postconditions: what we check

• create · unique-constraint-violation

  error
  WhenUnique constraint violation (duplicate key)
  ThrowsPrismaClientKnownRequestError with code 'P2002'
  Required handlingCaller MUST catch P2002 errors and handle duplicate key violations gracefully. Extract conflicting field from error.meta.target. DO NOT retry without changing the unique field value.
  costhighin prodimmediate exceptionusers seelost transactionvisibilityvisible
  Sources[1]
• create · foreign-key-constraint

  error
  WhenForeign key constraint violation
  ThrowsPrismaClientKnownRequestError with code 'P2003'
  Required handlingCaller MUST verify referenced record exists before creating. This indicates data integrity issue - DO NOT retry.
  costhighin prodimmediate exceptionusers seelost transactionvisibilityvisible
  Sources[2]
• create · required-field-missing

  error
  WhenRequired field is missing from data
  ThrowsPrismaClientValidationError
  Required handlingValidate data completeness before calling Prisma. This is a client-side error.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• create · connection-error

  error
  WhenDatabase connection failed
  ThrowsPrismaClientInitializationError or PrismaClientRustPanicError
  Required handlingCaller MUST handle connection errors separately from business logic errors. Implement exponential backoff retry for transient connection issues. Alert operations if connection errors persist.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4]
• update · record-not-found

  error
  WhenRecord to update does not exist
  ThrowsPrismaClientKnownRequestError with code 'P2025'
  Required handlingCaller MUST handle P2025 (record not found) errors. Decide whether to: 1. Create the record, 2. Return error to user, or 3. Silently ignore. DO NOT retry update on non-existent record.
  costhighin prodimmediate exceptionusers seelost transactionvisibilityvisible
  Sources[5]
• update · unique-constraint-violation

  error
  WhenUpdate would violate unique constraint
  ThrowsPrismaClientKnownRequestError with code 'P2002'
  Required handlingCheck if new value conflicts with existing record. DO NOT retry.
  costhighin prodimmediate exceptionusers seelost transactionvisibilityvisible
  Sources[1]
• update · foreign-key-constraint

  error
  WhenUpdate would violate foreign key constraint
  ThrowsPrismaClientKnownRequestError with code 'P2003'
  Required handlingVerify referenced record exists. This indicates data integrity issue.
  costmediumin prodimmediate exceptionusers seelost transactionvisibilityvisible
  Sources[2]
• update · connection-error

  error
  WhenDatabase connection failed
  ThrowsPrismaClientInitializationError
  Required handlingImplement retry with exponential backoff
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• delete · record-not-found

  error
  WhenRecord to delete does not exist
  ThrowsPrismaClientKnownRequestError with code 'P2025'
  Required handlingCaller MUST handle P2025 errors. Decide if missing record is acceptable (idempotent delete). DO NOT retry delete on non-existent record.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5]
• delete · foreign-key-constraint

  error
  WhenCannot delete because of foreign key constraint (dependent records exist)
  ThrowsPrismaClientKnownRequestError with code 'P2003' or 'P2014'
  Required handlingCaller MUST either: 1. Delete dependent records first (cascade delete), or 2. Return error to user. Check referencing tables before attempting delete.
  costhighin prodimmediate exceptionusers seelost transactionvisibilityvisible
  Sources[7]
• delete · connection-error

  error
  WhenDatabase connection failed
  ThrowsPrismaClientInitializationError
  Required handlingImplement retry with exponential backoff
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• findUnique · record-not-found

  error
  WhenRecord with specified ID does not exist
  Returnsnull
  Required handlingCaller MUST check if result is null before accessing properties. Code that assumes findUnique always returns a record will crash.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[8]
• findUnique · connection-error

  error
  WhenDatabase connection failed
  ThrowsPrismaClientInitializationError
  Required handlingImplement retry with exponential backoff
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• findUniqueOrThrow · record-not-found

  error
  WhenRecord with specified ID does not exist
  ThrowsPrismaClientKnownRequestError with code 'P2025'
  Required handlingCaller MUST catch P2025 errors when using findUniqueOrThrow. This method throws instead of returning null, requiring explicit error handling.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[9]
• findUniqueOrThrow · connection-error

  error
  WhenDatabase connection failed
  ThrowsPrismaClientInitializationError
  Required handlingImplement retry with exponential backoff
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• $transaction · transaction-failed

  error
  WhenAny operation in transaction fails
  ThrowsPrismaClientKnownRequestError (various codes) or PrismaClientUnknownRequestError
  Required handlingCaller MUST handle transaction failures. All operations are rolled back. Identify which operation failed using error.code and error.meta. Consider retry strategy for transient errors (connection issues).
  costhighin prodimmediate exceptionusers seelost transactionvisibilityvisible
  Sources[10]
• $transaction · deadlock-error

  error
  WhenTransaction deadlock detected by database
  ThrowsPrismaClientKnownRequestError with code 'P2034'
  Required handlingCaller SHOULD implement retry logic for deadlock errors. Use exponential backoff with jitter to reduce contention. Consider redesigning transaction to reduce lock duration.
  costhighin prodimmediate exceptionusers seelost transactionvisibilityvisible
  Sources[11]
• $transaction · connection-error-in-transaction

  error
  WhenConnection lost during transaction
  ThrowsPrismaClientInitializationError
  Required handlingTransaction is automatically rolled back. Retry entire transaction. Implement idempotency if retrying critical transactions (payments, etc).
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[12]
• $transaction · transaction-timeout

  warning
  WhenTransaction exceeded max duration
  ThrowsPrismaClientKnownRequestError with code 'P2024'
  Required handlingBreak transaction into smaller units or increase timeout. Long transactions hold locks and can cause performance issues.
  costmediumin prodimmediate exceptionusers seelost transactionvisibilityvisible
  Sources[13]
• $connect · connection-failed

  error
  WhenUnable to establish database connection
  ThrowsPrismaClientInitializationError
  Required handlingCaller MUST handle connection failures. Common causes: 1. Database server is down 2. Invalid connection string 3. Network issues 4. Database authentication failure Implement retry with exponential backoff for transient errors.
  costcriticalin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4]
• $disconnect · disconnect-with-pending-queries

  warning
  WhenDisconnecting while queries are pending
  ThrowsMay throw errors for pending queries
  Required handlingCaller SHOULD await all pending queries before calling $disconnect. Use in graceful shutdown handlers (SIGTERM, SIGINT).
  costmediumin prodimmediate exceptionusers seelost transactionvisibilityvisible
  Sources[14]
• upsert · upsert-race-condition-unique-constraint

  error
  WhenConcurrent upserts targeting the same non-existent record
  ThrowsPrismaClientKnownRequestError with code 'P2002'
  Required handlingWhen multiple upsert operations run concurrently for the same record, one may throw P2002 (unique constraint violation) because another operation created the record first. Caller MUST catch P2002 and retry the upsert to trigger the update branch. DO NOT treat P2002 on upsert as an unrecoverable error.
  costhighin prodimmediate exceptionusers seelost transactionvisibilityvisible
  Sources[15][1]
• upsert · upsert-foreign-key-constraint

  error
  WhenUpsert violates a foreign key constraint (referenced record does not exist)
  ThrowsPrismaClientKnownRequestError with code 'P2003'
  Required handlingCaller MUST verify all referenced (foreign key) records exist before upserting. A P2003 on upsert indicates referential integrity would be violated. DO NOT retry — fix the data before retrying.
  costmediumin prodimmediate exceptionusers seelost transactionvisibilityvisible
  Sources[2]
• upsert · upsert-connection-error

  error
  WhenDatabase connection failed during upsert
  ThrowsPrismaClientInitializationError
  Required handlingImplement retry with exponential backoff for transient connection errors.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• createMany · createmany-unique-constraint-violation

  error
  WhenOne or more records in the batch violate a unique constraint
  ThrowsPrismaClientKnownRequestError with code 'P2002'
  Required handlingCaller MUST either: 1. Use skipDuplicates: true to silently skip conflicting records (where supported), OR 2. Catch P2002 and report which records failed. Note: skipDuplicates is NOT supported on MongoDB, SQL Server, or SQLite — on those databases, a unique violation fails the entire batch.
  costhighin prodimmediate exceptionusers seelost transactionvisibilityvisible
  Sources[16][1]
• createMany · createmany-foreign-key-constraint

  error
  WhenOne or more records reference a non-existent foreign key
  ThrowsPrismaClientKnownRequestError with code 'P2003'
  Required handlingEntire batch is rejected on the first foreign key violation. Caller MUST validate all referenced IDs exist before calling createMany.
  costhighin prodimmediate exceptionusers seelost transactionvisibilityvisible
  Sources[2]
• createMany · createmany-connection-error

  error
  WhenDatabase connection failed during batch insert
  ThrowsPrismaClientInitializationError
  Required handlingEntire batch fails on connection loss. Implement retry with idempotency checks (e.g., use skipDuplicates or pre-check which records were already inserted).
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• updateMany · updatemany-unique-constraint-violation

  error
  WhenUpdate would cause a unique constraint violation across the matched batch
  ThrowsPrismaClientKnownRequestError with code 'P2002'
  Required handlingIf setting a field to a value that conflicts with existing unique records, updateMany throws P2002. Caller MUST validate uniqueness or catch P2002 and roll back dependent changes.
  costhighin prodimmediate exceptionusers seelost transactionvisibilityvisible
  Sources[1]
• updateMany · updatemany-zero-rows-affected-not-error

  warning
  WhenNo records match the where clause
  Returns{ count: 0 } — does NOT throw
  Required handlingUnlike update(), updateMany does NOT throw P2025 when zero records match. It returns { count: 0 }. Caller MUST check the returned count if zero-match is an unexpected business condition that should be treated as an error.
  costhighin prodsilent failureusers seelost datavisibilitysilent
  Sources[17]
• updateMany · updatemany-connection-error

  error
  WhenDatabase connection failed during bulk update
  ThrowsPrismaClientInitializationError
  Required handlingImplement retry with exponential backoff.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• deleteMany · deletemany-foreign-key-constraint

  error
  WhenRecords to delete are referenced by other tables via foreign keys
  ThrowsPrismaClientKnownRequestError with code 'P2003' or 'P2014'
  Required handlingCaller MUST delete or nullify dependent records before calling deleteMany, OR rely on cascade delete rules configured in the schema. A partial batch failure rolls back all deletes.
  costhighin prodimmediate exceptionusers seelost transactionvisibilityvisible
  Sources[2][7]
• deleteMany · deletemany-zero-rows-not-error

  warning
  WhenNo records match the where clause
  Returns{ count: 0 } — does NOT throw
  Required handlingUnlike delete(), deleteMany does NOT throw P2025 when zero records match. It returns { count: 0 }. If zero-match indicates a logic error (e.g., deleting a user's data that should exist), caller MUST check the count.
  costmediumin prodsilent failureusers seelost datavisibilitysilent
  Sources[18]
• deleteMany · deletemany-connection-error

  error
  WhenDatabase connection failed during bulk delete
  ThrowsPrismaClientInitializationError
  Required handlingImplement retry with idempotency check (verify records still exist before retrying).
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• findFirst · findfirst-null-not-checked

  error
  WhenNo record matches the filter
  Returnsnull
  Required handlingCaller MUST check if result is null before accessing properties. Code that assumes findFirst always returns a record will crash with "Cannot read properties of null" at the property access site, not at the findFirst call — making bugs hard to trace.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[19]
• findFirst · findfirst-connection-error

  error
  WhenDatabase connection failed
  ThrowsPrismaClientInitializationError
  Required handlingImplement retry with exponential backoff.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• findFirstOrThrow · findfirstorthrow-record-not-found

  error
  WhenNo record matches the filter
  ThrowsPrismaClientKnownRequestError with code 'P2025'
  Required handlingCaller MUST catch P2025 when using findFirstOrThrow. This method is designed for lookups where a missing record is an error condition. Unhandled P2025 crashes the request.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[20][5]
• findFirstOrThrow · findfirstorthrow-connection-error

  error
  WhenDatabase connection failed
  ThrowsPrismaClientInitializationError
  Required handlingImplement retry with exponential backoff.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• $queryRaw · queryraw-sql-injection-via-unsafe-interpolation

  error
  WhenUser input interpolated into query using Prisma.raw() or string concatenation
  ThrowsPrismaClientKnownRequestError (malformed query) or silent data exfiltration
  Required handlingALWAYS use tagged template literal syntax: prisma.$queryRaw`SELECT * FROM ...` NEVER use string concatenation or Prisma.raw() with user-supplied input. Unsafe interpolation bypasses Prisma's parameterization and enables SQL injection. Use $queryRawUnsafe ONLY when you control 100% of the query string.
  costcriticalin prodsilent failureusers seelost datavisibilitysilent
  Sources[21]
• $queryRaw · queryraw-type-mismatch

  warning
  WhenSQL return columns do not match the TypeScript generic type T
  ThrowsRuntime type error at property access — TypeScript does not validate raw results
  Required handlingValidate raw query results at runtime (e.g. with Zod) before using them. TypeScript generics on $queryRaw<T> are not enforced — the cast is unsafe. Extra columns, null columns, or type differences cause runtime errors elsewhere.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[22]
• $queryRaw · queryraw-connection-error

  error
  WhenDatabase connection failed during raw query
  ThrowsPrismaClientInitializationError
  Required handlingImplement retry with exponential backoff for transient connection failures.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• $executeRaw · executeraw-sql-injection-via-unsafe-interpolation

  error
  WhenUser input interpolated into mutation using Prisma.raw() or string concatenation
  ThrowsSilent data corruption or PrismaClientKnownRequestError
  Required handlingALWAYS use tagged template literal syntax: prisma.$executeRaw`UPDATE ...` NEVER pass user input through Prisma.raw() or string interpolation. Use $executeRawUnsafe ONLY when the SQL string is fully developer-controlled.
  costcriticalin prodsilent failureusers seelost datavisibilitysilent
  Sources[21]
• $executeRaw · executeraw-zero-rows-not-error

  warning
  WhenSQL mutation affects zero rows
  Returns0 — does NOT throw
  Required handling$executeRaw returns the number of affected rows. A return value of 0 is NOT an error condition by default. Caller MUST check the return value if zero-affected rows indicates a business logic failure (e.g., updating a record that should exist).
  costhighin prodsilent failureusers seelost datavisibilitysilent
  Sources[23]
• $executeRaw · executeraw-prepared-statement-restriction

  error
  WhenDDL statements (ALTER TABLE, CREATE TABLE, etc.) attempted via $executeRaw
  ThrowsPrismaClientKnownRequestError — database rejects DDL in prepared statement context
  Required handling$executeRaw uses prepared statements which cannot execute DDL statements on most databases. Use $executeRawUnsafe for DDL, or run migrations through Prisma Migrate instead. Never attempt schema changes via $executeRaw in application code.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[24]
• $executeRaw · executeraw-connection-error

  error
  WhenDatabase connection failed during raw mutation
  ThrowsPrismaClientInitializationError
  Required handlingImplement retry with exponential backoff. Ensure idempotency before retrying mutations.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• findMany · findmany-empty-array-not-checked

  warning
  WhenNo records match the filter
  Returns[] (empty array) — does NOT throw
  Required handlingfindMany returns an empty array when no records match — it does NOT throw. Caller MUST check result.length if zero results indicate a business error (e.g. listing a tenant's records that should always have >=1 row). Silent-empty results often manifest as blank UI rather than visible errors.
  costmediumin prodsilent failureusers seelost datavisibilitysilent
  Sources[25]
• findMany · findmany-connection-error

  error
  WhenDatabase connection failed during query
  ThrowsPrismaClientInitializationError
  Required handlingImplement retry with exponential backoff for transient connection errors.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• findMany · findmany-pagination-unbounded

  warning
  WhenfindMany called without take/skip pagination on large tables
  ReturnsAll matching rows — can be unbounded
  Required handlingWithout `take` and `skip` (or `cursor`-based pagination), findMany loads the entire result set into memory and across the wire. On large tables this can cause OOM in the app process and database client buffer overflows. ALWAYS paginate user-facing queries.
  costmediumin proddegraded serviceusers seedegraded performancevisibilityvisible
  Sources[26]
• count · count-zero-result-silent

  warning
  WhenNo records match the where clause
  Returns0 — does NOT throw
  Required handlingcount() returns 0 silently when no rows match. If zero-count indicates a business condition (e.g. tenant has no records but should), caller MUST treat 0 as an alert condition explicitly. Don't pass count() result directly into business logic without a zero-check.
  costmediumin prodsilent failureusers seelost datavisibilitysilent
  Sources[27]
• count · count-connection-error

  error
  WhenDatabase connection failed during count query
  ThrowsPrismaClientInitializationError
  Required handlingImplement retry with exponential backoff for transient connection errors.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• aggregate · aggregate-null-when-no-rows

  error
  WhenNo records match the where clause
  Returns{ _min: { field: null }, _max: { field: null }, _avg: { field: null }, _sum: { field: null }, _count: 0 }
  Required handlingWhen no rows match, aggregate returns null for _min/_max/_avg/_sum fields (not 0, not undefined — null). Code that does `result._sum.amount + tax` will crash with "Cannot read properties of null". Caller MUST null-check every aggregate field before arithmetic or comparison. The _count field returns 0 (not null) when no rows match.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[28]
• aggregate · aggregate-connection-error

  error
  WhenDatabase connection failed during aggregation
  ThrowsPrismaClientInitializationError
  Required handlingImplement retry with exponential backoff for transient connection errors.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• groupBy · groupby-empty-array-not-checked

  warning
  WhenNo records match the filter
  Returns[] (empty array) — does NOT throw
  Required handlinggroupBy returns an empty array when no records match. Code that assumes at least one group exists (e.g. dashboard charts) MUST handle empty arrays. Empty groupBy results often manifest as blank charts rather than visible errors.
  costmediumin prodsilent failureusers seelost datavisibilitysilent
  Sources[29]
• groupBy · groupby-having-validation-error

  error
  Whenhaving clause references field not in by clause
  ThrowsPrismaClientValidationError
  Required handlingThe fields used in `having` must also appear in `by` or be aggregations. Dynamic queries that build `having` from user input MUST validate the field list against the `by` list before sending to Prisma.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[30]
• groupBy · groupby-connection-error

  error
  WhenDatabase connection failed during groupBy query
  ThrowsPrismaClientInitializationError
  Required handlingImplement retry with exponential backoff for transient connection errors.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• createManyAndReturn · createmanyandreturn-unsupported-provider

  error
  WhenCalled on MySQL, MongoDB, or SQL Server
  ThrowsPrismaClientValidationError or runtime error — provider does not support RETURNING
  Required handlingcreateManyAndReturn is supported only on PostgreSQL, CockroachDB, and SQLite. On unsupported providers, calls throw at runtime. Detect the provider via schema introspection or use createMany + a separate findMany on the unique keys when targeting MySQL/MongoDB/SQL Server.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[31]
• createManyAndReturn · createmanyandreturn-unique-constraint-violation

  error
  WhenOne or more records violate a unique constraint
  ThrowsPrismaClientKnownRequestError with code 'P2002'
  Required handlingIdentical to createMany: caller MUST either use skipDuplicates: true OR catch P2002. When P2002 fires, the entire batch is rolled back and NO rows are returned. Idempotency requires inspecting which rows were already present before retry.
  costhighin prodimmediate exceptionusers seelost transactionvisibilityvisible
  Sources[1]
• createManyAndReturn · createmanyandreturn-foreign-key-constraint

  error
  WhenOne or more records reference a non-existent foreign key
  ThrowsPrismaClientKnownRequestError with code 'P2003'
  Required handlingEntire batch is rejected on the first foreign key violation. Caller MUST validate all referenced IDs exist before calling.
  costhighin prodimmediate exceptionusers seelost transactionvisibilityvisible
  Sources[2]
• createManyAndReturn · createmanyandreturn-connection-error

  error
  WhenDatabase connection failed during batch insert
  ThrowsPrismaClientInitializationError
  Required handlingEntire batch fails on connection loss. Implement retry with idempotency checks.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• updateManyAndReturn · updatemanyandreturn-unsupported-provider

  error
  WhenCalled on MySQL, MongoDB, or SQL Server
  ThrowsPrismaClientValidationError or runtime error — provider does not support RETURNING
  Required handlingupdateManyAndReturn is supported only on PostgreSQL, CockroachDB, and SQLite. On unsupported providers, calls throw at runtime. Use updateMany + a separate findMany when targeting MySQL/MongoDB/SQL Server.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[32]
• updateManyAndReturn · updatemanyandreturn-zero-rows-empty-array

  warning
  WhenNo records match the where clause
  Returns[] (empty array) — does NOT throw P2025
  Required handlingUnlike update(), updateManyAndReturn does NOT throw when zero records match — it returns []. Caller MUST check result.length if zero-match indicates a business error (e.g. updating a record that should exist).
  costhighin prodsilent failureusers seelost datavisibilitysilent
  Sources[32]
• updateManyAndReturn · updatemanyandreturn-unique-constraint-violation

  error
  WhenUpdate would cause a unique constraint violation
  ThrowsPrismaClientKnownRequestError with code 'P2002'
  Required handlingIf setting a field to a value that conflicts with existing unique records, updateManyAndReturn throws P2002. Caller MUST validate uniqueness or catch P2002.
  costhighin prodimmediate exceptionusers seelost transactionvisibilityvisible
  Sources[1]
• updateManyAndReturn · updatemanyandreturn-connection-error

  error
  WhenDatabase connection failed during bulk update
  ThrowsPrismaClientInitializationError
  Required handlingImplement retry with exponential backoff.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• $queryRawUnsafe · queryrawunsafe-sql-injection

  error
  WhenUser input concatenated into the SQL string
  ThrowsSilent data exfiltration, data corruption, or PrismaClientKnownRequestError on malformed SQL
  Required handling$queryRawUnsafe is documented as UNSAFE and bypasses Prisma's parameterization. NEVER pass user-supplied strings directly. Either: 1. Use $queryRaw with tagged template literals (parameterized), OR 2. Pass values as the second-arg array: $queryRawUnsafe(sql, ...params) — the ...params arguments ARE parameterized; only the SQL string is unsafe. Auditors will flag any $queryRawUnsafe call. Document why it was necessary and prove the SQL string contains no user input.
  costcriticalin prodsilent failureusers seesecurity breachvisibilitysilent
  Sources[33][34]
• $queryRawUnsafe · queryrawunsafe-connection-error

  error
  WhenDatabase connection failed during raw query
  ThrowsPrismaClientInitializationError
  Required handlingImplement retry with exponential backoff for transient connection failures.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• $queryRawUnsafe · queryrawunsafe-type-mismatch

  warning
  WhenSQL return columns do not match the TypeScript generic type T
  ThrowsRuntime type error at property access — TypeScript does not validate raw results
  Required handlingValidate raw query results at runtime (e.g. with Zod) before using them. TypeScript generics on $queryRawUnsafe<T> are not enforced — the cast is unsafe.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[24]
• $executeRawUnsafe · executerawunsafe-sql-injection

  error
  WhenUser input concatenated into the SQL string
  ThrowsSilent data corruption, unauthorized writes, or PrismaClientKnownRequestError
  Required handling$executeRawUnsafe is documented as UNSAFE for the SQL string. Mutation equivalent of $queryRawUnsafe — same SQL injection risk PLUS write/delete impact. NEVER concatenate user input into the SQL. Either: 1. Use $executeRaw with tagged template literals (parameterized), OR 2. Pass values via the ...params second-arg array: $executeRawUnsafe(sql, ...params). Audit every call site and document why a parameterized $executeRaw is insufficient.
  costcriticalin prodsilent failureusers seesecurity breachvisibilitysilent
  Sources[35][34]
• $executeRawUnsafe · executerawunsafe-zero-rows-not-error

  warning
  WhenSQL mutation affects zero rows
  Returns0 — does NOT throw
  Required handlingReturns the number of affected rows. 0 is NOT an error condition by default. Caller MUST check the return value if zero-affected rows indicates a business logic failure.
  costhighin prodsilent failureusers seelost datavisibilitysilent
  Sources[24]
• $executeRawUnsafe · executerawunsafe-connection-error

  error
  WhenDatabase connection failed during raw mutation
  ThrowsPrismaClientInitializationError
  Required handlingImplement retry with exponential backoff. Ensure idempotency before retrying mutations.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]

Sources

Every postcondition cites at least one of these. Grouped by source type; numbered to match the footnotes above.

Research notes

Curator notes from SOURCES.md captured when the profile was written so you can verify the reasoning, not just the rules.

import { Prisma } from "@prisma/client";

try {
  const user = await prisma.user.create({ data: { email } });
} catch (e) {
  if (e instanceof Prisma.PrismaClientKnownRequestError) {
    if (e.code === 'P2002') {
      // Unique constraint violation
      const target = e.meta?.target; // Field that caused violation
      // Handle duplicate key error
    }
  }
  throw e; // Re-throw unexpected errors
}