Error codes

Prisma's user-facing error codes are P2xxx. The full reference is in Prisma docs. This page focuses on internal code conventions and the codes that exist outside the documented public reference.

Code ranges

• P2000–P2037 — documented in the public error reference. Most are constraint violations, validation failures, and well-known DB conditions. Map to specific MappedError kinds in packages/client-engine-runtime/src/user-facing-error.ts.
• P2038 — PrismaClientInitializationError from ClientEngine when no driver adapter is configured. Source: CLIENT_ENGINE_ERROR in packages/client/src/runtime/core/engines/client/ClientEngine.ts. Prisma 7 introduced this because, unlike the old engine, the new client cannot fall back to a default DB connection without an adapter.
• P2039 — fallback for unmapped database-specific driver-adapter errors. Format: Database error. Code: <originalCode>. Message: <originalMessage>. Returned for non-raw queries when the adapter recognized the error as MappedError.kind === 'postgres' / 'mysql' / 'sqlite' / 'mssql' but didn't have a more specific mapping for the original code. Used so schema-drift-style errors stay debuggable instead of becoming opaque HTTP 500s.

The next available code for new mappings is P2040.

Raw query path

Raw queries ($executeRaw, $queryRaw, $executeRawUnsafe, $queryRawUnsafe) take a different path through rethrowAsUserFacingRawError and always return P2010 with format Raw query failed. Code: <originalCode>. Message: <originalMessage>. Even unmapped DB errors stay at P2010 in the raw path; P2039 is used for non-raw queries so the message doesn't claim a regular Prisma operation was a raw query.

Adding a new code

From AGENTS.md:

1. Add a new kind to MappedError in packages/driver-adapter-utils/src/types.ts.
2. Map the database error code in each affected adapter's errors.ts.
3. Add the Prisma code mapping in getErrorCode() and the message in renderErrorMessage() in packages/client-engine-runtime/src/user-facing-error.ts.
4. Update AGENTS.md so the next contributor doesn't reuse the code.
5. Document it in this wiki.

Public error classes

Class	Caught by user code	When
PrismaClientKnownRequestError	Yes	Database-side error mapped to a P2xxx code
PrismaClientUnknownRequestError	Yes	Engine error without a known code
PrismaClientRustPanicError	Yes	Schema Engine panic (rare; binary crashed)
PrismaClientInitializationError	Yes	Setup failure (P2038 etc.)
PrismaClientValidationError	Yes	User input failed validation before reaching the engine

Defined in packages/client/src/runtime/core/errors/.

Asserting on errors in tests

Per AGENTS.md:

// ✅ Robust across realms (e.g., generated client in subdirectory)
expect(result.name).toBe('PrismaClientKnownRequestError');
expect(result.code).toBe('P2002');

// ❌ Fails when the error class is from a different module realm
expect(result).toBeInstanceOf(PrismaClientKnownRequestError);

See also

• MappedError
• @prisma/client-engine-runtime for rethrowAsUserFacing
• Driver adapters for the per-adapter mapping
• Patterns and conventions