できない.dev

SQLite「UNIQUE constraint failed」の原因と直し方

UNIQUE constraint failed は、UNIQUE か PRIMARY KEY の列に既にある値を INSERT すると出る。
エラー文の「テーブル.列」で当たった制約を特定し、重複を除くか ON CONFLICT で更新か無視に切り替えれば直る。

公開: 更新:

症状できない · exit 19
sqlite3 app.db "INSERT INTO users (email, name) VALUES ('a@example.com', 'B');"
Error: stepping, UNIQUE constraint failed: users.email (19)
解決後できた · exit 0
sqlite3 app.db "CREATE UNIQUE INDEX idx_contacts_email ON contacts (email);"

2026-11-06 に python:3.12(SQLite 3.46.1) で実際に打って取った出力。検証環境の詳細

要約

email に UNIQUE を付けたテーブルへ同じメールアドレスをもう一度入れると、SQLite 3.46.1 の sqlite3 コマンドは次のように止まった。

Error: stepping, UNIQUE constraint failed: users.email (19)

UNIQUE constraint failed は、UNIQUE か PRIMARY KEY の列に、既にある値を入れようとしたことを示す。
末尾の users.email が当たった制約の「テーブル.列」で、(19) は制約違反を表す結果コード SQLITE_CONSTRAINT の番号である。
Python の sqlite3 では IntegrityError として送出され、Python 3.11 以降は sqlite_errorname が SQLITE_CONSTRAINT_UNIQUE になった。

実行例

python:3.12 のコンテナの SQLite 3.46.1 で、users.email・users.id・複合 UNIQUE・重複が残った列への CREATE UNIQUE INDEX の 4 通りを試すと、すべて UNIQUE constraint failed で終了コード 19 になった。
ON CONFLICT・INSERT OR REPLACE・INSERT OR IGNORE は終了コード 0 で、重複を削除したあとの CREATE UNIQUE INDEX も通った。

$ sqlite3 --version
3.46.1 2024-08-13 09:16:08 c9c2ab54ba1f5f46360f1b4f35d849cd3f080e6fc2b6c60e91b16c63f69aalt1 (64-bit)
$ sqlite3 app.db "INSERT INTO users (email, name) VALUES ('a@example.com', 'B');"
Error: stepping, UNIQUE constraint failed: users.email (19)
$ echo $?
19
$ sqlite3 app.db "INSERT INTO users (id, email, name) VALUES (1, 'c@example.com', 'C');"
Error: stepping, UNIQUE constraint failed: users.id (19)
$ echo $?
19
$ sqlite3 app.db "INSERT INTO members VALUES (1, 10);"
Error: stepping, UNIQUE constraint failed: members.user_id, members.group_id (19)
$ echo $?
19
$ sqlite3 app.db "CREATE UNIQUE INDEX idx_contacts_email ON contacts (email);"
Error: stepping, UNIQUE constraint failed: contacts.email (19)
$ echo $?
19
$ sqlite3 app.db "SELECT * FROM users WHERE email = 'a@example.com';"
1|a@example.com|A
$ sqlite3 app.db "INSERT INTO users (email, name) VALUES ('a@example.com', 'B') ON CONFLICT(email) DO UPDATE SET name = excluded.name;"
$ echo $?
0
$ sqlite3 app.db "SELECT * FROM users;"
1|a@example.com|B
$ sqlite3 app.db "INSERT OR REPLACE INTO users (email, name) VALUES ('a@example.com', 'C');"
$ echo $?
0
$ sqlite3 app.db "SELECT * FROM users;"
2|a@example.com|C
$ sqlite3 app.db "INSERT OR IGNORE INTO users (email, name) VALUES ('a@example.com', 'D'); SELECT changes();"
0
$ echo $?
0
$ sqlite3 app.db "SELECT email, COUNT(*) FROM contacts GROUP BY email HAVING COUNT(*) > 1;"
x@example.com|2
$ sqlite3 app.db "DELETE FROM contacts WHERE rowid NOT IN (SELECT MIN(rowid) FROM contacts GROUP BY email);"
$ sqlite3 app.db "CREATE UNIQUE INDEX idx_contacts_email ON contacts (email);"
$ echo $?
0

— 2026-11-06 時点の出力

検証環境Python 3.12.16 / Git 2.47.3 / SQLite 3.46.1 / 2026-11-06 検証
検証日
実行環境
python:3.12 Debian GNU/Linux 13 (trixie)
バージョン
  • Python 3.12.16
  • Git 2.47.3
  • SQLite 3.46.1

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

1. 既にある行を確かめる

SELECT * FROM users WHERE email = 'a@example.com';

行が返るなら、アプリ側で同じ値を 2 回入れている。
入れる前に存在を確かめるか、次の UPSERT にまとめる。

2. 既にあれば更新する

INSERT INTO users (email, name) VALUES ('a@example.com', 'B')
  ON CONFLICT(email) DO UPDATE SET name = excluded.name;

excluded.name は、衝突しなければ入るはずだった値を指す。
上の文はエラーにならず、既存の行の name だけが B に変わった。
UPSERT は SQLite 3.24.0 以降で使える(UPSERT(新しいタブで開く))。

INSERT OR REPLACE でもエラーは消えるが、既存の行を削除してから入れ直す。
実際に試すと、id が 1 から 2 に変わった。
他のテーブルから id で参照しているなら、REPLACE ではなく UPSERT を使う。

3. 重複は飛ばす

INSERT OR IGNORE INTO users (email, name) VALUES ('a@example.com', 'B');
SELECT changes();

衝突した行だけが黙って飛ばされ、changes() は 0 を返した。
飛ばしたことがアプリに伝わらないので、件数を確かめたい場合は changes() を見る。

4. インデックスを作る前に重複を片付ける

SELECT email, COUNT(*) FROM users GROUP BY email HAVING COUNT(*) > 1;

返ってきた値の行を、残す 1 行を決めて削除してから CREATE UNIQUE INDEX を実行する。

よくある原因

  1. UNIQUE の列に同じ値を入れている。
    登録処理を二重に実行した、テストデータを毎回同じ値で入れている、といった場合に起きる。
  2. 主キーを自分で指定している。
    id INTEGER PRIMARY KEY に既存と同じ 1 を入れると UNIQUE constraint failed: users.id になった。
    id を省くと、SQLite は通常いちばん大きい id に 1 を足した値を振る。
  3. 複合の UNIQUE に同じ組み合わせを入れている。
    この場合は m.user_id, m.group_id のように列が並んで表示された。
  4. 重複が残ったまま UNIQUE インデックスを作っている。
    CREATE UNIQUE INDEX も同じエラーで失敗する。

大文字小文字が違う値(a@example.com と A@example.com)は、既定では別の値として入った。
逆に NULL は互いに等しくないとみなされ、UNIQUE の列に 2 行入った。