Required entity lookup
A service method requires a uniquely identified record and should fail immediately when it is absent.
Prisma · Module
findUniqueOrThrow
findUniqueOrThrow retrieves one record using a unique lookup and throws PrismaClientKnownRequestError when no record matches. Unlike findUnique, its successful result is non-nullable.
- Since
- 4.0.0
How it works
Call this Prisma Client method when a unique lookup must succeed. It performs the same lookup as findUnique, but throws PrismaClientKnownRequestError when no matching record exists, so successful results are non-nullable.
Syntax
prisma.model.findUniqueOrThrow(args)Parameters
| Name | Type | Description |
|---|---|---|
args | UserFindUniqueOrThrowArgs | Arguments for the model's unique-record query, including the unique where filter and optional result-selection or relation options. |
Returns
A non-nullable record of the model queried; throws PrismaClientKnownRequestError when no matching record is found.
Key points
- A missing matching record produces PrismaClientKnownRequestError.
- TypeScript can treat the successful result as present without a null check.
- The successful result is the model record rather than a nullable model-or-null union.
- Interactive transactions are the documented workaround when transactional rollback is needed.
Common mistakes
- In an array-form transaction, a not-found error does not roll back earlier operations; use an interactive transaction when atomic rollback is required.
- Handle the thrown error explicitly, especially when the call follows writes in a sequential transaction.
Example: Require a unique record
const user = await prisma.user.findUniqueOrThrow({
where: { email: "alice@prisma.io" },
});
console.log(user.email);Looks up a user by a unique field and returns a non-nullable record; an absent user causes the call to throw.
When to use it
Fail-fast request handling
An API handler already maps domain errors and wants missing data to enter its exception path.
Transactional validation
A transaction must use callback-based interactive semantics to ensure a not-found exception can trigger rollback.
Interview questions
QHow does findUniqueOrThrow behave when no record exists?
It retrieves one record using the same unique lookup rules as findUnique. If no record matches, it throws PrismaClientKnownRequestError instead of returning null.
Follow-up: What type does it return on success? A non-nullable model type, so callers do not need a null check after a successful await.
QHow does its return type differ from findUnique?
The method's result is non-nullable, unlike findUnique, whose result can be a model or null. This makes absence an exception path rather than a value path.
Follow-up: When is findUnique preferable? Use it when a missing record is expected and should be represented as null rather than an exception.
QWhat transaction limitation does the documentation describe?
It cannot be used safely with sequential operations in the array form of $transaction when rollback is required. A thrown PrismaClientKnownRequestError does not roll back the other array operations.
Follow-up: What transaction form should be used instead? Use an interactive transaction callback so the operations can be rolled back when the lookup throws.
Related
findUnique()findFirstOrThrow()$transaction APIPrismaClientKnownRequestError