SQLITE_CONSTRAINT_UNIQUEERRORTier 2 — Caution⚠️ MEDIUM confidenceUNIQUE constraint failed
🔴 Production Risk Error
Medium — UPSERT patterns handle this gracefully.
What this means
SQLITE_CONSTRAINT_UNIQUE (2067) is returned when an INSERT or UPDATE would create a duplicate value in a column (or combination of columns) declared UNIQUE.
Why it happens
- 1Inserting a row whose UNIQUE column value already exists in the table.
- 2Bulk import containing duplicate values in a unique-constrained column.
How to reproduce
INSERT or UPDATE violating a UNIQUE constraint.
import sqlite3
conn = sqlite3.connect(':memory:')
conn.execute('CREATE TABLE users(email TEXT UNIQUE)')
conn.execute("INSERT INTO users VALUES('a@b.com')")
try:
conn.execute("INSERT INTO users VALUES('a@b.com')")
except sqlite3.IntegrityError as e:
print(e) # UNIQUE constraint failed: users.emailFix 1
Why this works
Use INSERT OR IGNORE to skip duplicates silently.
Fix 2
Why this works
Use INSERT OR REPLACE to overwrite the existing row.
Fix 3
Why this works
Use the UPSERT clause: INSERT ... ON CONFLICT(email) DO UPDATE SET ...
Fix 4
Why this works
Check for existence before inserting: SELECT 1 FROM users WHERE email=?
What not to do
Why it's wrong:
Sources
📚 Official docs: https://www.sqlite.org/rescode.html#constraint_unique
🔧 Source ref: sqlite3.h — SQLITE_CONSTRAINT_UNIQUE = 2067
📖 Further reading: SQLite UPSERT
Confidence assessment
⚠️ MEDIUM confidence
Stable.
See also
🔗 Related errors
📄 Reference pages