MySQL Error 1062: Duplicate Entry

MySQL error 1062 (Duplicate Entry) explained: what it means, why it happens, and how to fix it — with copy-paste code examples.

MySQL Error Code 1062 MySQL Last verified 2026-08-19

Quick Answer

Read the full message: it names the duplicate value and the key ('Duplicate entry X for key Y'). If that does not apply, for idempotent inserts use `INSERT ... ON DUPLICATE KEY UPDATE col=VALUES(col)` or `INSERT IGNORE` — the full checklist is below.

Error Code

MySQL Error Code: 1062
Official name: Duplicate Entry
Service: MySQL

What does this error mean?

Duplicate entry '%s' for key %s

Common Causes

How to Fix

  1. Read the full message: it names the duplicate value and the key ('Duplicate entry X for key Y')
  2. For idempotent inserts use `INSERT ... ON DUPLICATE KEY UPDATE col=VALUES(col)` or `INSERT IGNORE`
  3. Use `SELECT ... FOR UPDATE` inside a transaction for check-then-insert flows where the key is business-critical
  4. Find and remove existing duplicates with a GROUP BY ... HAVING COUNT(*) > 1 query before retrying
  5. Surface a clear 409-style error to API callers instead of leaking the raw duplicate message

Code Examples

Idempotent upsert sql 
INSERT INTO users (email, name)
VALUES ('ada@example.com', 'Ada')
ON DUPLICATE KEY UPDATE
  name = VALUES(name);

When the unique key already exists, the UPDATE branch runs instead of failing with 1062.

Find the duplicates sql 
SELECT email, COUNT(*)
FROM users
GROUP BY email
HAVING COUNT(*) > 1;

Locates existing rows that share a unique value so you can clean them before retrying.

Framework-Specific Fixes

nodejs-mysql2

Catch the driver error, check err.code === 'ER_DUP_ENTRY', and map it to HTTP 409 with the duplicate key name.

try {
  await pool.query(
    'INSERT INTO users (email) VALUES (?) ON DUPLICATE KEY UPDATE email = email',
    [email],
  )
} catch (err) {
  if (err.code === 'ER_DUP_ENTRY') return res.status(409).json({ error: 'Email already taken' })
  throw err
}
python-sqlalchemy

Let IntegrityError propagate to a handler that inspects the underlying driver code 1062.

from sqlalchemy.exc import IntegrityError
try:
    session.add(user)
    session.commit()
except IntegrityError as e:
    if e.orig.args[0] == 1062:
        raise DuplicateUser(email) from e
    raise
php-pdo

Check errorInfo[1] === 1062 after catching PDOException and return 409.

try {
  $pdo->exec("INSERT INTO users (email) VALUES ('$email')");
} catch (PDOException $e) {
  if ($e->errorInfo[1] === 1062) { http_response_code(409); exit('email exists'); }
  throw $e;
}

You Might Also Like

1048 Column Cannot Be Null Column '%s' cannot be null 1452 Foreign Key Constraint Fails on Insert Cannot add or update a child row: a foreign key constraint fails (%s) 1364 Field Doesn't Have a Default Value Field '%s' doesn't have a default value PostgreSQL23505 Unique Violation A unique constraint or exclusion constraint was violated while inserting or updating a row, because a… PrismaP2002 Unique Constraint Failed Unique constraint failed on the {constraint}

Frequently Asked Questions

Why am I seeing MySQL error 1062?

Most often this happens when inserting or updating a row whose value collides with an existing unique key (email, username, order number, external id), or when retrying an insert after a timeout or partial failure, so the row was actually created but the retry hits the unique index.

How do I fix MySQL error 1062?

Read the full message: it names the duplicate value and the key ('Duplicate entry X for key Y').

Which frameworks have documented fixes for error 1062?

This page documents fixes for: nodejs-mysql2, python-sqlalchemy, php-pdo.

Official Sources

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