LaravelでAPP_KEYが設定されていない場合の対処方法

Laravelで「APP_KEYが設定されていない」状態になると、アプリケーションの暗号化機能が正常に動かず、起動時や特定処理で例外が発生する。Laravelの暗号化キーは config/app.php の key 設定に対応しており、その値は通常 APP_KEY 環境変数から読み込まれる。Laravel公式でも、暗号化機能を使う前に APP_KEY を設定し、php artisan key:generate で安全なキーを生成することが案内されている。

APP_KEYとは何か

APP_KEYは、Laravelの暗号化・復号に使われるアプリケーションキー。Cookie、セッション、暗号化された値などの保護に関わる中核設定で、Laravelの config/app.php の key は APP_KEY 環境変数により決まる。キー生成には php artisan key:generate を使うのが公式の推奨手順になっている。

このエラーが発生する条件

発生しやすい条件は次の通り。
・新規でLaravelプロジェクトを作成した直後に .env を整備していない
・.env ファイル自体が存在しない
・APP_KEY= が空のまま
・デプロイ先で環境変数が未設定
・.env を変更したのに設定キャッシュが古いまま残っている
Laravelは設定値を config 経由で読み込むため、環境変数や設定キャッシュの不整合でもこの問題が起きる。

よく出る症状

症状としては、以下のような形で現れることが多い。
・アプリ起動時に500エラー
・「No application encryption key has been specified.」系の例外
・ログインやセッション処理で失敗
・暗号化/復号を使う処理が落ちる
Laravelの暗号化機能は APP_KEY を前提にしているため、キーが無いと起動はしても重要処理で落ちやすい。

最短の対処：php artisan key:generate を実行する

最も基本的な対処は、Laravel公式が案内している key:generate コマンドを実行すること。これにより、PHPの安全な乱数生成を使って暗号学的に安全なキーが生成され、.env の APP_KEY に書き込まれる。

php artisan key:generate

成功すると、.env の APP_KEY= に base64: から始まる値が入る。

.envファイルが無い場合の対処

key:generate を実行しても .env が無いと、期待通りに書き込めないことがある。まずは .env.example をコピーして .env を作成する。

cp .env.example .env
php artisan key:generate

Windows環境ではコピーコマンドが異なるため、エクスプローラーやPowerShellで .env.example を .env に複製してから同じく php artisan key:generate を実行する流れになる。

.envにAPP_KEYが入っているか確認する

コマンド実行後は、.env に値が入っているかを確認する。正常なら次のような形式になる。

APP_KEY=base64:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=

ここが空のままだったり、途中で切れていたり、余計な引用符や空白が混ざっていると、正しく読み込めず再び同じエラーになることがある。

設定キャッシュが原因で直らない場合

.env を修正したのにエラーが消えない場合、設定キャッシュが古い可能性が高い。Laravelの公式設定ドキュメントにある通り、設定はキャッシュできるため、更新後はクリアまたは再生成が必要になる。

php artisan config:clear
php artisan cache:clear

本番運用で設定キャッシュを使っているなら、必要に応じて再生成する。

php artisan config:cache

Dockerや本番サーバーで起きやすい原因

ローカルでは直ったのに、本番やDockerだけ APP_KEY エラーが出ることがある。多い原因は次の通り。
・コンテナ内に .env が存在しない
・環境変数をコンテナへ渡していない
・デプロイ時に .env が上書き/未配置
・読み取り専用ファイルシステムで key:generate が書き込めない
・設定キャッシュがビルド時のまま残っている
この場合は「本番では .env を置くのか」「環境変数として注入するのか」を先に決め、その方式に統一するのが重要になる。

本番でやってはいけないこと

本番環境でAPP_KEYを気軽に再生成するのは危険。Laravel 11以降ではキーのローテーション手段も提供されているが、現在の APP_KEY を変更すると、既存の暗号化データやセッション、Cookieの復号に影響が出る可能性がある。Laravel 11では APP_PREVIOUS_KEYS を使って旧キーを複数保持しながら段階的に移行する仕組みが用意されている。

つまり、本番で「とりあえず key:generate」を実行すると、
・ログインセッション切れ
・暗号化済みデータの復号失敗
・一部機能の突然の不整合
が起こりうる。既存運用中の本番では、キー変更は計画的に行う必要がある。

新規開発環境と既存本番環境で対応を分ける

対応は環境によって変わる。
新規ローカル環境なら、.env を作って php artisan key:generate を実行すればほぼ解決する。
既に運用中の本番環境なら、現在のキーの有無・暗号化済みデータの有無・セッション影響・ローテーション方針を確認してから対応する必要がある。Laravel 11以降では APP_PREVIOUS_KEYS を使った移行手段もある。

サンプル手順：新規環境での安全な復旧フロー

新しく clone したLaravelアプリで APP_KEY エラーが出た場合の基本フローは次の通り。

cp .env.example .env
composer install
php artisan key:generate
php artisan config:clear
php artisan migrate
php artisan serve

この順で進めると、.env 作成、依存導入、APP_KEY生成、設定反映、DB準備まで一通り揃えやすい。

チェックリスト

APP_KEY エラーが出たときは、次を順番に確認すると切り分けが速い。
・.env は存在するか
・APP_KEY= に値が入っているか
・php artisan key:generate を実行したか
・設定キャッシュをクリアしたか
・Docker/本番で環境変数が正しく渡っているか
・本番で既存キーを不用意に変えていないか
・Laravel 11以降なら APP_PREVIOUS_KEYS による移行が必要な状況ではないか

まとめ

LaravelでAPP_KEYが設定されていない場合、まず確認すべきは .env の有無と APP_KEY の値。そのうえで、公式が推奨する php artisan key:generate を実行し、必要なら設定キャッシュをクリアするのが基本対応になる。新規開発環境ではこれでほぼ解決するが、既存本番環境では暗号化済みデータやセッションへの影響があるため、キーの再生成は慎重に扱う必要がある。Laravel 11以降では APP_PREVIOUS_KEYS によるローテーション支援も用意されているため、運用中のシステムではその仕組みも視野に入れて対応すると安全。