Prisma Error P2002: Unique Constraint Failed

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
System name: Unique constraint failed
Service: Prisma

What does this error mean?

Unique constraint failed on the {constraint}

Common Causes

• Creating or updating a record whose value collides with an existing row on a unique field (email, username, slug, external id)
• Using create() where an upsert() would be correct, so the second request fails on the unique index
• Concurrent requests racing to insert the same unique value (signups, order numbers) without conflict handling
• Seeding or re-importing data that was partially applied, leaving duplicates in the target table

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

Example Scenario

await prisma.user.create({ data: { email } }) runs during a double-submit: the user clicked Sign Up twice, the first request committed, and the second throws PrismaClientKnownRequestError: Unique constraint failed on the fields: (email), with code P2002. The meta.target field lists the exact constrained fields, and the same P2002 wraps SQLSTATE 23505 (Postgres) or 1062 (MySQL) whichever engine you run on.

Diagnostic Commands

Run these to confirm the cause before applying a fix — each command answers a specific question.

catch (e) {
  if (e instanceof Prisma.PrismaClientKnownRequestError) {
    console.log(e.code, e.meta?.target); // P2002 ['email']
  }
}

model User {
  id    Int    @id @default(autoincrement())
  email String @unique
}

Decision Guide

Expected duplicate (signup / retry)?
├─ catch P2002 → return a friendly 'already exists' response
│   if (e.code === 'P2002') return conflict('Email already registered')
└─ prefer the atomic upsert:
    prisma.user.upsert({ where: { email },
      create: { email }, update: { lastSeenAt: new Date() } })

Unexpected duplicate (seed / import)?
└─ inspect the existing row first:
    prisma.user.findUnique({ where: { email } })

Code Examples

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

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

Framework-Specific Fixes

@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
  }
}

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
}

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

You Might Also Like

Frequently Asked Questions

Recommended Tools

Recommendations are editorial — DB Error Reference takes no payment or affiliate fees for tool listings.

Official Sources

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

• Prisma Client and Prisma Migrate errors (Error Reference)official