MySQL error 1062 (Duplicate entry), explained and fixed

ERROR 1062 (23000): Duplicate entry '[email protected]' for key 'users.email_unique' means a write tried to put a value into a uniquely constrained column (or combination) that already exists in another row. The message names the value and the key, which together identify the rule that fired, a primary key or any UNIQUE index. Nothing is broken: the database is enforcing a rule someone defined, and the application attempted a write that violates it. The work is deciding what a duplicate should mean in this part of the application, then handling it deliberately.

Decide what a duplicate means here

  1. Read the key name: the primary key failing on an insert with an explicit id suggests an id collision or a re-import of existing data; a business column like an email or a SKU failing suggests a genuine “already exists” situation the user or process should hear about.
  2. Check whether the row already there is the same entity (a retried registration, a double-submitted form, an import run twice) or a different entity that happens to share the value (two people, one shared email). The remedy differs completely.

The handling options, honestly compared

  1. Report it: for user-facing uniqueness (usernames, emails), catch error 1062 and turn it into a clear message. Letting the raw database error reach the user is the failure, not the constraint.
  2. INSERT ... ON DUPLICATE KEY UPDATE when the intent is “insert or refresh”: an upsert that updates the existing row's mutable fields. Right for imports and synchronization, wrong for registrations (it would silently overwrite someone's record).
  3. INSERT IGNORE converts the error to a warning and skips the row; appropriate for idempotent bulk loads, dangerous anywhere the application needs to know the write did not happen, and it downgrades other error classes to warnings as well.
  4. Fix the id generation when primary keys collide: sequences or auto-increment values desynchronized after a restore or a manual insert with explicit ids; reseeding the counter above the current maximum is the repair.
Do not “fix” 1062 by removing the unique constraint unless the rule itself was wrong. The constraint is the only thing standing between the application and silently duplicated accounts, orders, or payments; the error is the cheapest possible place to learn about the collision.

Common questions

Why does a retried request trigger it when the first one “failed”? The first attempt often succeeded at the database and failed afterward (a timeout in the response path), so the retry meets the row the first attempt created. Idempotency handling, upserts or checking first, is the systematic fix.

Can duplicates appear on a replica or after restore? Yes, when writes bypass the constraint's protection (broken replication, restored data loaded with checks relaxed, or auto-increment drift). The error is then a symptom; compare the data and counters rather than handling it as an application event.

Which key is 'PRIMARY' in the message? The table's primary key. A 1062 on PRIMARY with auto-generated ids usually means explicit ids were inserted (imports, fixtures) that collide with generated ones, or the auto-increment counter fell behind the data.

Related errors

MySQL error 1045 (Access denied) · SQLite: database is locked · SQL Server error 1205 (deadlock)