Prisma Error P2002: Unique Constraint Failed

Prisma error P2002 (Unique Constraint Failed) explained: what it means, why it happens, and how to fix it — with copy-paste code examples.

Error code P2002 Prisma Last verified 2026-08-19

Quick Answer

Read error.meta.target to see exactly which field(s) violated the unique constraint. If that does not apply, decide the intended behavior: reject the write, update the existing row, or skip it — the full checklist is below.

Error Code

Error code: P2002
Official name: Unique Constraint Failed
Service: Prisma

What does this error mean?

Unique constraint failed on the {constraint}

Common Causes

How to Fix

  1. Read error.meta.target to see exactly which field(s) violated the unique constraint
  2. Decide the intended behavior: reject the write, update the existing row, or skip it
  3. Switch create() to upsert() with the unique field in the where clause for idempotent writes
  4. If duplicates already exist, locate and remove them with Prisma Studio or a SQL query before retrying
  5. Add application-level idempotency (client-generated ids or retry-on-unique) for concurrent flows

Code Examples

Idempotent create with upsert typescript 
const user = await prisma.user.upsert({
  where: { email: 'ada@example.com' },
  update: { lastLoginAt: new Date() },
  create: { email: 'ada@example.com' },
})

upsert() checks the unique field first and updates the existing row instead of throwing P2002.

Catch P2002 and read the conflicting field typescript 
try {
  await prisma.user.create({ data: input })
} catch (e) {
  if (e instanceof Prisma.PrismaClientKnownRequestError && e.code === 'P2002') {
    console.error('conflicting field:', e.meta.target)
  }
}

e.meta.target names the unique field, which is what you want to surface in the API response.

Framework-Specific Fixes

nestjs

Catch PrismaClientKnownRequestError in a global exception filter and map code P2002 to HTTP 409 Conflict with the conflicting field.

@Catch(Prisma.PrismaClientKnownRequestError)
export class PrismaExceptionFilter implements ExceptionFilter {
  catch(e, host) {
    if (e.code === 'P2002') {
      return response.status(409).json({
        message: `Duplicate value on ${e.meta.target}`,
      })
    }
    throw e
  }
}
express

Wrap create/update calls in a helper that translates P2002 into a 409 response so the API never crashes on duplicates.

try {
  await prisma.user.create({ data: { email } })
} catch (e) {
  if (e instanceof Prisma.PrismaClientKnownRequestError && e.code === 'P2002') {
    return res.status(409).json({ error: 'Email already exists' })
  }
  throw e
}
prisma-client

Prefer upsert() over create() whenever the operation must be idempotent on a unique field.

await prisma.user.upsert({
  where: { email },
  update: { name },
  create: { email, name },
})

You Might Also Like

P2003 Foreign Key Constraint Failed Foreign key constraint failed on the field: {field_name} P2011 Null Constraint Violation Null constraint violation on the {constraint} P2004 Constraint Failed on the Database A constraint failed on the database: {database_error} PostgreSQL23505 Unique Violation A unique constraint or exclusion constraint was violated while inserting or updating a row, because a… MySQL1062 Duplicate Entry Duplicate entry '%s' for key %s

Frequently Asked Questions

Why am I seeing Prisma error P2002?

Most often this happens when creating or updating a record whose value collides with an existing row on a unique field (email, username, slug, external id), or when using create() where an upsert() would be correct, so the second request fails on the unique index.

How do I fix Prisma error P2002?

Read error.meta.target to see exactly which field(s) violated the unique constraint.

Which frameworks have documented fixes for error P2002?

This page documents fixes for: nestjs, express, prisma-client.

Official Sources

This page is based on the official Prisma documentation linked below and adds practical troubleshooting guidance on top.