Fail-fast resource lookup
An API endpoint requires a matching resource and maps missing resources to an exception response.
Prisma · Module
findFirstOrThrow
findFirstOrThrow returns the first record matching a query and throws PrismaClientKnownRequestError when no record is found. Its result type is non-nullable.
- Since
- Prisma ORM 4
How it works
Call the model method with the same query arguments as findFirst. Prisma returns the first matching record, but when no record matches it throws a PrismaClientKnownRequestError; the returned type is non-nullable, so callers do not need a null check.
Syntax
prisma.<model>.findFirstOrThrow(<args>)Parameters
| Name | Type | Description |
|---|---|---|
args | FindFirstArgs<Model> | Arguments for the model's findFirst query, including filtering, ordering, pagination, relation loading, and field selection options. |
Returns
The first matching record with a non-nullable type; throws PrismaClientKnownRequestError when no record is found.
Key points
- A successful call produces a record type that does not include null.
- Choose this method when a missing match should be represented by an exception.
- Compared with findFirst, this method avoids a nullable result after successful execution.
Common mistakes
- A missing record is exceptional: handle the thrown Prisma error rather than expecting a null result.
- Unlike findFirst, this operation returns a non-nullable result.
Example: Retrieve the first matching record
const user = await prisma.user.findFirstOrThrow({
where: { email: "alice@prisma.io" },
orderBy: { id: "asc" },
});
console.log(user.email);Looks up the first matching user and throws instead of returning null when no match exists.
When to use it
Required record retrieval
A script or job should stop when a required database record is absent.
Ordered first-match selection
A query needs the first item from an ordered set and absence is invalid.
Interview questions
QWhat does findFirstOrThrow do when no record matches?
findFirstOrThrow retrieves one record using the same criteria as findFirst. If no record matches, it throws a PrismaClientKnownRequestError rather than returning null.
Follow-up: How does its type differ from findFirst? Its return type is non-nullable, which removes the need for a null check after a successful call.
QHow is findFirstOrThrow related to findFirst?
It accepts the query arguments used by findFirst, such as where, orderBy, select, and include. The query returns the first record matching those criteria.
Follow-up: How can ordering affect the selected record? Supplying orderBy makes which matching record is first explicit instead of relying on an unspecified order.
QWhen would you choose findFirstOrThrow?
Use it when absence should cause the operation to fail and the caller already handles exceptions. It is useful for routes and scripts that want fail-fast behavior instead of branching on null.
Follow-up: When should findFirst be preferred? Use findFirst when no match is an expected outcome that the application should handle as a nullable result.
Related
findFirstfindUniqueOrThrowPrismaClientKnownRequestError