Request error handling
Map a known Prisma error to an application response.
Prisma · Class
PrismaClientKnownRequestError
Prisma Client uses PrismaClientKnownRequestError for query-engine errors that are known to be related to a request, such as a unique-constraint violation. Its properties provide the error code, contextual metadata, message, and Client version.
How it works
This exception represents a request-related error that the query engine has classified. Handle it by checking the Prisma-specific code and using the accompanying metadata, message, and client version for diagnosis or application-level responses.
Syntax
new Prisma.PrismaClientKnownRequestError(message, code, clientVersion, meta)Returns
An exception object with code, meta, message, and clientVersion properties.
Key points
- Use
codeto branch on the particular Prisma error returned for the request. - Use
metafor structured context, such as the field responsible for the failure. - Use
messagefor the human-readable text associated with the error code. - Use
clientVersionto record which Prisma Client release produced the exception.
Common mistakes
- The class is for errors classified by the query engine as known request errors; it is not a general wrapper for every possible failure.
Example: Inspect a known Prisma request error
import { PrismaClient, Prisma } from '@prisma/client'
const prisma = new PrismaClient()
async function main() {
try {
await prisma.user.create({
data: { email: 'existing@example.com' }
})
} catch (error) {
if (error instanceof Prisma.PrismaClientKnownRequestError) {
console.error(error.code, error.meta, error.message)
}
} finally {
await prisma.$disconnect()
}
}
main()Catches the known-request exception and reads its documented diagnostic properties.
When to use it
Constraint diagnostics
Investigate which model field triggered a constraint failure.
Version-aware logging
Correlate failures with the deployed Prisma Client release.
Interview questions
QWhen does Prisma Client throw PrismaClientKnownRequestError?
It is thrown when the query engine returns a known error related to a Prisma Client request. A unique-constraint violation is one documented example.
Follow-up: Which property should application code inspect to distinguish known error cases? Inspect code, which contains the Prisma-specific error code.
QWhat diagnostic properties does the exception expose?
The code property identifies the Prisma-specific error, while meta supplies additional context such as the field involved. message contains the associated error text.
Follow-up: How can a handler investigate which field caused a uniqueness failure? Examine meta, whose example contains a target array with the relevant field name.
QWhat is the purpose of clientVersion?
The exception includes clientVersion, which identifies the Prisma Client version, in addition to the error code, metadata, and message. These values can be logged or used to choose handling logic.
Follow-up: Why retain the client version in diagnostics? It helps correlate behavior with the exact Prisma Client release running the request.
Related
PrismaClientRustPanicErrorPrismaClientInitializationErrorPrismaClientValidationErrorPrismaClientUnknownRequestError