prisma/prisma

MappedError

The normalized error shape every driver adapter produces. Defined in packages/driver-adapter-utils/src/types.ts. Translated into Prisma's public P2xxx error codes by rethrowAsUserFacing in packages/client-engine-runtime/src/user-facing-error.ts.

Why it exists

Each underlying driver throws differently:

pg throws an Error with a .code like '23505'
mysql2 throws with .errno and .code like 'ER_DUP_ENTRY'
mssql throws with .number
SQLite drivers wrap errors with .errno

MappedError is the normalization point. Every adapter has a convertDriverError function (packages/adapter-*/src/errors.ts) that translates the driver's error into a MappedError of a known kind.

Known kinds

From AGENTS.md (the canonical list):

Cross-database

GenericJs — anything else
UnsupportedNativeDataType
InvalidIsolationLevel
LengthMismatch

Constraints

UniqueConstraintViolation
NullConstraintViolation
ForeignKeyConstraintViolation

Connectivity

DatabaseNotReachable
DatabaseDoesNotExist
DatabaseAlreadyExists
DatabaseAccessDenied
ConnectionClosed
TlsConnectionError
AuthenticationFailed
TooManyConnections
SocketTimeout

Schema

TableDoesNotExist
ColumnNotFound
MissingFullTextSearchIndex

Transactions

TransactionWriteConflict
TransactionAlreadyClosed

Values

ValueOutOfRange
InvalidInputValue
InconsistentColumnData

Database-specific fallbacks — postgres, mysql, sqlite, mssql. These carry the raw originalCode and originalMessage for cases the adapter didn't recognize.

Translation pipeline

graph LR
    DBError[Driver throws] --> AdapterMap[adapter-*/errors.ts<br/>convertDriverError]
    AdapterMap --> Mapped[MappedError]
    Mapped --> Rethrow[user-facing-error.ts<br/>rethrowAsUserFacing]
    Rethrow --> Pxxxx[PrismaClientKnownRequestError P2xxx]

rethrowAsUserFacing() matches on MappedError.kind:

Known cross-database kinds → specific Prisma codes (P2002 unique violation, P2003 foreign key, etc.)
DB-specific kinds with unrecognized originalCodes → P2039 fallback with format Database error. Code: <originalCode>. Message: <originalMessage>
Truly unknown kind values → assertNever (so new variants surface during development)

Raw queries

$executeRaw / $queryRaw go through rethrowAsUserFacingRawError instead. It always returns P2010 with format Raw query failed. Code: <originalCode>. Message: <originalMessage>. Raw queries are a single, well-known case where users are running their own SQL.

Adding a new mapping

Step-by-step from AGENTS.md:

Add the kind to MappedError in packages/driver-adapter-utils/src/types.ts.
Map the database error code in each affected adapter's errors.ts (packages/adapter-pg/src/errors.ts, etc.).
Add Prisma code mapping in getErrorCode() and message in renderErrorMessage() in packages/client-engine-runtime/src/user-facing-error.ts.
Document the new code in AGENTS.md so future contributors don't reuse it.

Currently assigned codes outside the public reference

P2038 — PrismaClientInitializationError from ClientEngine when no driver adapter is configured (packages/client/src/runtime/core/engines/client/ClientEngine.ts, CLIENT_ENGINE_ERROR).
P2039 — fallback for unmapped database-specific driver-adapter errors (described above).

The next available code for new additions is P2040.