タグアーカイブ インデックス

WordPressのキーが長すぎるエラーをMariaDB 11.4で修正する方法

「指定されたキーが長すぎます。最大キー長は 1000 バイトです」というエラーが WordPress サイトのデータベースで発生した場合、対象となるテーブルの複合インデックス定義で長すぎるカラムのプレフィックス長を制限すれば解決する。これはデータベースの照合順序と文字コードの関係で、インデックスが許容バイト数を超過することが直接の原因だ。

「キーが長すぎる」エラーが発生する根本原因

このエラーは特定のデータベーステーブルに複合インデックスを作成しようとした際に、インデックスに含まれるカラムの合計バイト数がデータベースの上限を超えたために発生する。MariaDB や MySQL では、InnoDB ストレージエンジンの行フォーマットとサーバー設定によってキー長の上限が決まる。具体的には ROW_FORMAT が COMPACT または REDUNDANT のテーブルでは最大 767 バイトまでしか許容されず、DYNAMIC や COMPRESSED の場合でも実質的に 3072 バイトが上限となる。

今回のようなエラーが顕在化しやすいのは、データベースを MariaDB の最新バージョン（11.4 系など）に移行したタイミングだ。デフォルトの文字コードが utf8mb4 に設定されている環境で、VARCHAR 型のカラムをインデックスに含めると、1 文字が最大 4 バイトとして計算されるため、たとえば VARCHAR(255) のカラムが含まれているだけで、そのカラムだけで 1020 バイトを消費する計算になる。

プラグインが独自に追加した CHANGE_LOG テーブルでは、object_type、object_id、created_at という 3 つのカラムで複合インデックスを作ろうとしている。object_id は外部キーや参照用に VARCHAR で定義されていることが多く、これが長いままだとバイト数制限に引っかかる。解決の本質は、インデックスで実際に使用する範囲を object_id カラムの先頭部分だけに限定することにある。

エラーを特定するための確認手順

実際のエラーメッセージをログから確認する

データベースエラーの内容を正確に把握するために、まずは WordPress のデバッグログを有効化する。wp-config.php に以下の定数を追加する。

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

エラーを再現させたあと、/wp-content/debug.log を確認すると「Specified key was too long; max key length is 1000 bytes」というエラーが記録されているはずだ。このエラーには対象のテーブル名や、キーを作成しようとした SQL 文も含まれている。

テーブルのインデックス定義を直接調べる

データベース管理ツール（phpMyAdmin など）で CHANGE_LOG テーブルの構造を開き、「インデックス」タブを確認する。object_lookup という名前の複合インデックスが存在し、そこに object_id カラムがフルサイズで含まれていれば、これがエラーの原因だと特定できる。

SQL コマンドに慣れているなら、以下のクエリでインデックス情報を取得してもよい。

SHOW INDEX FROM wp_change_log;

文字コードとバイト数の関係を理解する

utf8mb4 は 1 文字を最大 4 バイトで表現するため、VARCHAR(255) として定義されたカラムは、インデックス上で最大 1020 バイトを占める。複合インデックスでは、含まれる全カラムの最大バイト数の合計が制限値となる。VARCHAR(100) なら最大 400 バイト、VARCHAR(50) なら 200 バイトと計算していき、上限（1000 バイトや 767 バイト）を超えていないかを確認する。この計算を怠ると、一見問題ない定義に見えても実行時にエラーとなる。

複合インデックスを修正する具体的な手順

修正の基本方針は object_lookup インデックスから既存の定義を削除し、object_id カラムのプレフィックス長を制限した新しいインデックスを作り直すことにある。これによりバイト数制限を回避しながら、インデックスの機能自体は維持できる。

このデモは object_id にプレフィックス長を設定する前後のインデックス定義の違いを表している。修正後はバイト数制限に収まるため、エラーが解消される。

phpMyAdmin で安全にインデックスを変更する

データベースの直接操作に不慣れな場合、phpMyAdmin を使うとミスが少ない。該当テーブルを開き、「構造」タブから「インデックス」セクションに移動する。object_lookup インデックスを選択して削除し、新たに「インデックスを作成」から複合インデックスを追加する。

カラムを選択する際、object_type と created_at はそのまま指定し、object_id だけ「サイズ」欄に 100 と入力する。これで object_id(100) としてインデックスが作成される。

SQL コマンドで直接修正する場合

コマンドラインや SQL タブから実行するなら、以下の 2 文を順に実行する。DROP で既存のインデックスを削除し、ADD で新しいインデックスを作成する。

ALTER TABLE wp_change_log DROP INDEX object_lookup;
ALTER TABLE wp_change_log ADD INDEX object_lookup (object_type, object_id(100), created_at);

実行前に必ずデータベースのバックアップを取得すること。誤った ALTER TABLE はテーブル構造を壊す可能性がある。

プラグインのアップデートで上書きされないようにする

このインデックスはプラグインが管理するスキーマファイル（class-change-log-schema.php）で定義されているため、プラグインがアップデートされると修正が上書きされてしまう可能性が高い。恒久的な対策としては、プラグインのアクティベーションフックやスキーマ更新処理にフックし、独自のインデックス定義を適用するコードを子テーマの functions.php かカスタムプラグインに記述する方法が有効だ。

データベースのバージョンや設定に依存する問題のため、サーバー環境を変更しない限りこの修正は必須となる。プラグイン開発者が将来的に修正を加えるまでは、自前のフックで対応しておくと安全だ。

よくある質問

このエラーは MariaDB 11.4 だけで発生するのか

MariaDB 11.4 に限らず、キー長制限が厳格に適用される環境ならば発生する可能性がある。古い MySQL 5.6 以前の設定や、InnoDB の ROW_FORMAT が COMPACT のテーブルでも同様のエラーが起こる。

object_id(100) のようにプレフィックスを制限しても検索性能は落ちないのか

先頭 100 文字までをインデックス化するため、100 文字を超える部分での検索精度は低下する可能性がある。ただ、object_id のような識別子は冒頭部分で十分に一意性が確保されることが多く、実際のクエリ性能に大きな影響は出ない。

エラーが WordPress 本体のテーブルで出た場合はどうすればよいか

WordPress コアのテーブルでこのエラーが発生することは稀だ。通常はプラグインやテーマが独自に追加したカスタムテーブルで起こる。もしコアテーブルで起こった場合は、データベースの文字コードや ROW_FORMAT の設定自体を見直す必要がある。

SQL の直接実行が不安なときの代替手段はあるか

WP-CLI（WordPress のコマンドライン管理ツール）が利用できるなら、「wp db query」コマンドで安全にクエリを実行できる。また、データベースの移行や最適化を支援するプラグイン（WP Migrate など）にも SQL 実行機能が備わっているものがある。

この記事のポイント

• インデックスに含まれるカラムの合計バイト数がデータベースの上限を超えるとキー長エラーが発生する
• utf8mb4 環境では VARCHAR 型のカラムが 1 文字最大 4 バイトを消費する点に注意が必要
• object_id(100) のようにカラムのプレフィックス長を指定してインデックスを再作成することでエラーを回避できる
• プラグインのアップデートで修正が上書きされるため、恒久的な対処にはフックを用いたコード管理が推奨される

佐々木 太陽

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