WordPressで「Duplicate entry」データベースエラーが出た時の原因と直し方

WordPressで「Duplicate entry」データベースエラーが出た時の原因と直し方

プラグイン更新後に debug.log へ「WordPress database error Duplicate entry」が大量出力される問題は、テーブルに一意キーを追加する際、既存データに空の値や重複が存在するために起きている。このエラーそのものはサイトの表示を直ちに壊すわけではないが、ログファイルが急激に肥大化してサーバーのディスク容量を圧迫するため、早期の対処が必要だ。

なぜこのエラーが発生するのか

プラグインのバージョンアップで、データベースのテーブル構造（スキーマ）が変更されることがある。今回のように wp_blc_links テーブルに url_hash カラムを追加し、さらにそのカラムへ UNIQUE KEY（一意キー制約）を設定しようとした場合、既存のレコードの中に同一のハッシュ値が重複していると「Duplicate entry」エラーが発生する。

とりわけ問題になるのが、ハッシュ値が空文字列（空の値）のまま残っているレコードだ。空文字列どうしも「同じ値」とみなされるため、一意キー制約に違反してエラーとなる。これは Broken Link Checker に限らず、データベースのスキーマ変更をともなうあらゆるプラグインで起こりうる。

エラーメッセージの後半に「for key 'wp_blc_links.url_hash'」と表示されているなら、url_hash 列の重複が原因と特定できる。この情報を手がかりに、次の対処へ進む。

まずはログの肥大化を止める

このエラーはサイトの表示に影響を与えないケースが多いが、放置すると debug.log が一晩で数百 MB に膨れ上がる。ディスク容量が尽きればサイト全体が停止するため、真っ先にログ出力を食い止める必要がある。

プラグインを前のバージョンに戻す

最も確実なのは、問題が発生しなかった旧バージョンへ差し戻す方法だ。プラグインの公式ページにある「以前のバージョン」セクションからダウンロードし、手動でアップロードして上書きする。WordPress 管理画面の「プラグイン」→「新規追加」→「プラグインのアップロード」から ZIP ファイルを指定すればよい。

プラグインを一時的に無効化する

旧バージョンの入手が難しい場合や、そもそもこのプラグインがサイト運営に必須でなければ、無効化するだけでログ出力は止まる。「プラグイン」→「インストール済みプラグイン」から該当プラグインを無効化するだけだ。無効化しても、これまでに収集されたリンク切れのデータはデータベースに残るため、後で有効化すれば以前の状態から再開できる。

上図は、プラグインのバージョンを戻すか無効化する前後でのログ出力の変化を表している。どちらの方法でも、エラーの無限出力はすぐに止められる。

データベースの重複を手動で修正する

プラグインの新バージョンを使い続けたい場合や、修正パッチのリリースを待たずに根本解決したい場合は、データベースを直接操作して重複レコードを削除する方法がある。ただし、操作を誤るとサイト全体に影響が出るため、必ず事前にデータベースのバックアップを取得しておく。

phpMyAdmin から重複行を特定して削除する

レンタルサーバーの管理画面から phpMyAdmin を開き、該当の WordPress データベースを選択する。wp_blc_links テーブル（接頭辞は環境により異なる）を表示し、「SQL」タブで次のクエリを実行すると、url_hash が空のレコードと重複しているレコードを確認できる。

SELECT url_hash, COUNT(*) 
FROM wp_blc_links 
GROUP BY url_hash 
HAVING COUNT(*) > 1;

このクエリで表示される行が、一意キー制約に違反する重複レコードだ。続けて、重複しているレコードのうち不要なものを削除する。url_hash が空文字列のレコードをすべて削除してしまえば、多くのケースでエラーは解消する。

DELETE FROM wp_blc_links WHERE url_hash = '';

削除後、プラグインを最新バージョンにアップデートするか、一度無効化してから再度有効化すれば、テーブルのスキーマ変更が正常に完了する。エラーログへの出力も止まるはずだ。

WP-CLI が使える環境での対処

サーバーに SSH 接続でき、WP-CLI がインストールされているなら、コマンドラインからより安全に操作できる。まずは重複を確認する。

wp db query "SELECT url_hash, COUNT(*) FROM wp_blc_links GROUP BY url_hash HAVING COUNT(*) > 1;"

問題が確認できたら、同様に空ハッシュのレコードを削除する。

wp db query "DELETE FROM wp_blc_links WHERE url_hash = '';"

操作後はプラグインを再有効化し、debug.log からエラーが消えたことを確認する。WP-CLI を使う最大の利点は、誤って操作しても wp db export で事前にバックアップを取りやすく、復旧が容易な点だ。

再発防止と注意点

プラグインのアップデートは自動更新に任せず、可能であればステージング環境で事前にテストする運用が望ましい。とくにデータベースのスキーマ変更をともなうアップデート（変更履歴に「database」「schema」「table」「column」といった単語が見られるもの）は要注意だ。

また、debug.log が常に有効になっている環境では、定期的にログファイルのサイズを確認し、不要になったら削除する習慣をつけておくと、ディスク容量の急激な枯渇を防げる。wp-config.php で WP_DEBUG_LOG を true にしている場合は、開発やトラブル解決時以外は false に戻しておくのも有効な対策だ。

よくある質問

重複レコードを削除してもプラグインの機能に影響はないのか

空のハッシュ値を持つレコードは、もともと正常にリンクチェックが機能していないデータだ。削除しても、プラグインは次回のクロール時に改めてリンクを検査して正しいハッシュ値を再生成するため、実害はない。むしろ重複が解消されることで、後続のアップデートも正常に完了するようになる。

このエラーを放置するとどうなるのか

エラーそのものはサイトのフロントエンド表示に影響しない場合が多いが、debug.log がサーバーのディスク容量を圧迫し、最悪の場合「ディスクフル」でサイト全体がダウンする。また、プラグインのスキーマ変更が完了しないため、以降のアップデートが正常に適用されず、プラグインの一部機能が動作しない状態が続く可能性もある。

Broken Link Checker 以外のプラグインでも同じエラーは起こるのか

起こる。UNIQUE KEY を追加するデータベーススキーマの変更を行うプラグインであれば、同種のエラーが発生しうる。SEO プラグインやセキュリティプラグインの大規模アップデートでも見られるため、エラーメッセージに表示されるテーブル名とカラム名を手がかりにして、同じ手順で対処できる。

phpMyAdmin を使えない場合はどうすればよいか

「WP Data Access」や「Advanced Database Cleaner」のようなデータベース操作ができるプラグインを一時的にインストールして、SQL クエリを実行する方法がある。あるいは、サーバー会社のサポートに依頼して重複レコードの削除を代行してもらうのも一つの手だ。

修正パッチがリリースされるまでのつなぎ対策は

プラグインを旧バージョンに固定し、WordPress 管理画面の「プラグイン」→「インストール済みプラグイン」で該当プラグインの自動更新をオフにしておく。公式の変更履歴を定期的にチェックし、修正が含まれたバージョンがリリースされたら手動でアップデートすればよい。

この記事のポイント

• 「Duplicate entry」エラーは、一意キー制約の追加時に既存データの重複が原因で発生する
• 緊急対応として、プラグインを旧バージョンに戻すか一時的に無効化する
• データベースから重複レコードを削除すれば、最新バージョンでも正常動作する
• 事前のバックアップ取得と、ステージング環境でのテストが再発防止に有効

佐々木 太陽

・ Reddit、Stack Overflow、WordPress.org フォーラムを日々巡回し、現場の悩みを拾い上げて記事化
・ WordPress、WooCommerce、Next.js などモダンWeb制作領域のトラブルシューティングが専門
・ 「検索しても答えが見つからなかった」を一つでも減らすことが目標
・ エラーメッセージから根本原因にたどり着く粘り強い調査が得意
・ 初心者がつまずきやすい箇所を先回りで解決する記事作りを心がけている