# sqlalchemy.exc.IntegrityError: (psycopg2.errors.UniqueViolation) duplicate key value violates unique constraint "users_email_key"

- **ID:** `python/sqlalchemy-integrity-error-duplicate`
- **Domain:** python
- **Category:** data_error
- **Verification:** ai_generated
- **Fix Rate:** 80%

## Root Cause

Inserting a record with a duplicate value in a unique column.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| 3.x | active | — | — |

## Workarounds

1. **Check for existing record before insert.** (95% success)
   ```
   existing = session.query(User).filter_by(email='test@example.com').first()
if not existing:
    session.add(User(email='test@example.com'))
session.commit()
   ```
2. **Use ON CONFLICT DO NOTHING via SQLAlchemy dialect.** (90% success)
   ```
   from sqlalchemy.dialects.postgresql import insert
stmt = insert(User).values(email='test@example.com').on_conflict_do_nothing()
session.execute(stmt)
session.commit()
   ```

## Dead Ends

- **Catching exception and ignoring without rollback.** — Transaction remains in aborted state; subsequent queries fail. (90% fail)
- **Using session.merge() without checking for conflicts.** — Merge may still raise IntegrityError if primary key conflicts. (60% fail)