Prisma P2025 Record Not Found— Fixed [Complete Guide 2026]
Also covers: update not found · delete not found · findUniqueOrThrow · nested connect
⚡ The Error You Are Seeing
PrismaClientKnownRequestError:
An operation failed because it depends on one or more records
that were required but not found.
code: 'P2025',
meta: {
modelName: 'User',
cause: 'Record to update not found.'
}What Causes Prisma P2025
P2025 fires whenever Prisma tries to operate on a record it cannot locate. The three most common triggers:
- Calling prisma.model.update() with a where clause that matches no row
- Calling prisma.model.delete() on an ID that does not exist
- Using connect: { id } inside a nested create/update for a relation that does not exist
Unlike P2002 which is about duplicates, P2025 is about absence. The fix pattern is always the same: either verify the record exists first, or catch P2025 and return a 404.
Catch P2025 and Return 404
Best practice for API routesimport { PrismaClientKnownRequestError } from "@prisma/client/runtime/library";
export function isPrismaError(error: unknown, code: string): boolean {
return (
error instanceof PrismaClientKnownRequestError &&
error.code === code
);
}import { prisma } from "@/lib/prisma";
import { isPrismaError } from "@/lib/prisma-error";
export async function PATCH(
request: Request,
{ params }: { params: { id: string } }
) {
const data = await request.json();
try {
const user = await prisma.user.update({
where: { id: params.id },
data,
});
return Response.json({ user });
} catch (error) {
if (isPrismaError(error, "P2025")) {
return Response.json(
{ error: "User not found" },
{ status: 404 }
);
}
throw error;
}
}Return HTTP 404 for P2025 — not 400 or 500. The record the client referenced simply does not exist.
Use findUnique Before update/delete
Explicit existence check patternWhen you need to use the existing record data in your response or logic, fetch it first with findUnique.
export async function updatePost(id: string, data: Partial<Post>) {
// Check existence first
const existing = await prisma.post.findUnique({
where: { id },
select: { id: true, authorId: true },
});
if (!existing) {
return { error: "Post not found", status: 404 };
}
// Optional: authorization check using existing data
if (existing.authorId !== currentUserId) {
return { error: "Forbidden", status: 403 };
}
const updated = await prisma.post.update({
where: { id },
data,
});
return { post: updated, status: 200 };
}Use findUniqueOrThrow
Cleaner API — no null checks neededPrisma's built-in findUniqueOrThrow throws P2025 automatically when a record is not found — eliminating null checks.
// BEFORE — null check required
const user = await prisma.user.findUnique({ where: { id } });
if (!user) throw new Error("Not found");
// AFTER — throws P2025 automatically, no null check needed
try {
const user = await prisma.user.findUniqueOrThrow({
where: { id },
include: { profile: true },
});
return user;
} catch (error) {
if (isPrismaError(error, "P2025")) {
return Response.json({ error: "User not found" }, { status: 404 });
}
throw error;
}P2025 on Nested Relation Updates
connect · disconnect · set on relationsWhen you use connect inside a nested write, Prisma looks up the related record. If it does not exist, P2025 fires.
// This throws P2025 if categoryId does not exist
await prisma.post.create({
data: {
title: "My Post",
category: { connect: { id: categoryId } }, // P2025 if missing
},
});
// Fix — validate the related record exists first
const category = await prisma.category.findUnique({
where: { id: categoryId },
select: { id: true },
});
if (!category) {
return Response.json({ error: "Category not found" }, { status: 404 });
}
await prisma.post.create({
data: { title: "My Post", category: { connect: { id: categoryId } } },
});P2025 on Delete — Use deleteMany Instead
Safe delete — never throws P2025The easiest way to avoid P2025 on delete operations: switch from delete() to deleteMany().
// BEFORE — throws P2025 if id doesn't exist
await prisma.post.delete({ where: { id } });
// AFTER — returns count, never throws P2025
const result = await prisma.post.deleteMany({
where: { id },
});
if (result.count === 0) {
return Response.json({ error: "Post not found" }, { status: 404 });
}
return Response.json({ deleted: true });deleteMany() is idempotent — perfect for webhooks or retry-able operations where the same delete may be called multiple times.
Prevention Checklist
- Use findUniqueOrThrow() instead of findUnique() when a missing record is always an error
- Catch P2025 in all update() and delete() calls and return HTTP 404
- Validate foreign key IDs before nested connect operations
- Use deleteMany() instead of delete() for safe, idempotent deletes
- Always re-throw non-P2025 errors — do not swallow unexpected exceptions
Frequently Asked Questions
What is Prisma error P2025?+−
How do I fix Prisma P2025 on update?+−
What is the difference between findUnique and findUniqueOrThrow?+−
Prisma update throwing P2025 — the record exists in the database. Why?+−
How do I safely delete a record without P2025?+−
P2025 on a nested connect — what does that mean?+−
Need Expert Help?
We Build Production-Grade Prisma Backends
Softplix architects and maintains Node.js backends with Prisma, PostgreSQL, and Next.js. Proper error handling included from day one.
Talk to an Engineer