こんにちは、かつコーチです。
ここまでルーティングやコントローラ、Eloquent、認証、キュー、スケジューラといった機能を順番に解説してきました。
今回からは少し毛色を変えて、「実践Tips・エラー解決」編に入っていきます。
初回は、Laravelを触っていると本当によく出会うエラーとその解決法を、まとめて紹介します。
「同じようなエラーで何度も検索している」という人も多いと思うので、この記事をブックマークしておいて、詰まったときに見返してもらえるとうれしいです。
Laravelのエラーが分かりにくい理由
フレームワーク特有のレイヤーの多さ
素のPHPと違って、Laravelは「ルーティング」「ミドルウェア」「コントローラ」「Eloquent」「Bladeテンプレート」など、処理が通過するレイヤーがたくさんあります。
エラーメッセージを見ても、「結局どのレイヤーで何が起きているのか」がすぐには分からず、初心者はここでつまずきやすいです。
エラー画面（Ignition）の読み方
Laravelの開発環境では、エラーが起きると詳細なエラー画面（Ignitionというパッケージ）が表示されます。
ここで見るべきポイントは主に3つです。
- エラーメッセージ本体：画面上部に表示される、エラーの種類と内容
- 該当ファイルと行数：エラーが発生したファイルパスと行番号がハイライトされる
- スタックトレース：どの処理からどの処理が呼ばれて、最終的にエラーに至ったかの経路
まずはエラーメッセージ本体を読み、次に該当ファイルの該当行を確認する、という順番で読み進めるのが基本の流れです。
慣れないうちは真っ赤な画面に圧倒されがちですが、実際に見るべき情報は限られています。
よくあるつまずきポイント①：ルーティング変更が反映されない
症状：ルートを書き換えたのにブラウザの表示が変わらない
私が実際に経験した、初心者〜中級者が特にハマりやすいトラブルがこれです。
routes/web.php のルーティングを書き換えて保存したのに、ブラウザをリロードしても古い挙動のまま変わらない、という現象です。
❌ Before：ルートキャッシュが残ったまま気づかず作業を続ける
<?php
// routes/web.php
// 元々こう書いていたが…
Route::get('/mypage', [MypageController::class, 'index']);
// これに書き換えた
Route::get('/mypage', [MypageController::class, 'show']);
コードを保存してブラウザをリロードしても、なぜか古い index メソッドの方が実行され続ける、という状態です。
私はこのとき、「コードのキャッシュが壊れているのかも」と思い込み、composer dump-autoload を実行したり、ブラウザのキャッシュを疑ってシークレットウィンドウで開き直したりと、見当違いな対処を繰り返してしまいました。
結局30分近く無駄にしてから、ようやく原因が「ルートキャッシュ」にあることに気づきました。
原因：本番環境向けに php artisan route:cache を一度でも実行していると、Laravelはルーティングの結果を1つのファイルとしてキャッシュします。
キャッシュが有効な間は、routes/web.php を書き換えても、Laravel側はキャッシュされたルート定義の方を優先して読み込むため、コードの変更が一切反映されません。
✅ After：route:clear でルートキャッシュを削除する
php artisan route:clear
このコマンドを実行してキャッシュを削除すれば、routes/web.php の最新の内容が正しく反映されるようになります。
ローカル開発中に「ルーティングを変えたのに反映されない」と感じたら、真っ先にこのコマンドを疑ってみてください。
恒久対策：開発中はルートキャッシュを作らない習慣をつける
そもそも開発中は route:cache を実行しない、というのが一番シンプルな予防策です。
route:cache は本番環境でルーティングの読み込みを高速化するためのコマンドなので、ローカル開発中に使う機会は基本的にありません。
もし「以前に一度実行した記憶があるが、いつ実行したか分からない」という状態であれば、次のコマンドで現在のキャッシュ状況を含めてクリアしておくと安全です。
php artisan optimize:clear
optimize:clear は、ルートキャッシュだけでなく、設定キャッシュ・ビューキャッシュ・イベントキャッシュなど、開発中に悪さをしがちなキャッシュ類をまとめて削除してくれるコマンドです。
「なぜか変更が反映されない」というトラブルに遭遇したら、まずこれを実行してみる、という習慣をつけておくと余計な調査時間を減らせます。
よくあるつまずきポイント②：.env を書き換えても反映されない
症状：APP_ENVやDB接続情報を変えたのに古い設定のまま
.env ファイルを書き換えたのに、アプリの挙動が変わらない、というのもよくあるトラブルです。
これも原因はルートキャッシュと同じで、設定キャッシュ（config:cache）が有効になっていることが多いです。
❌ Before：設定キャッシュが残った状態で.envだけ書き換える
# .envを編集してDB_DATABASEを変更
# → しかしconfig:cacheが有効なため反映されない
config:cache を一度実行すると、Laravelは .env の値を含めた設定情報をキャッシュファイルに固めてしまいます。
以後は .env を直接見にいかず、キャッシュファイルの内容を使うようになるため、.env をいくら書き換えても反映されません。
✅ After：設定キャッシュもクリアする
php artisan config:clear
ルートキャッシュと設定キャッシュは、どちらも「本番環境の高速化のための仕組みが、開発中に悪さをする」という構造がそっくりなので、セットで覚えておくとよいでしょう。
よくあるつまずきポイント③：SQLSTATE 系のデータベースエラー
症状：SQLSTATE[HY000] [1049] Unknown database が出る
Eloquentやマイグレーションを実行したときに出る代表的なエラーの一つです。
SQLSTATE[HY000] [1049] Unknown database 'laravel_app'
これは、.env に指定した DB_DATABASE の名前のデータベースが、実際にはMySQL側にまだ作られていない場合に発生します。
✅ 対処法
# MySQLに接続してデータベースを作成する
mysql -u root -p -e "CREATE DATABASE laravel_app;"
# その後マイグレーションを実行する
php artisan migrate
.env にデータベース名を書いただけでは、データベース自体は自動で作られません。
必ず事前にMySQL側でデータベースを作成しておく必要がある、という点を忘れないようにしましょう。
症状：SQLSTATE[42S02] Table not found
こちらは、テーブル自体がまだ存在していないことを示すエラーです。
原因のほとんどは、マイグレーションを実行し忘れているケースです。
php artisan migrate
「モデルは作ったのに、対応するテーブルを作るマイグレーションを実行し忘れていた」というのは、Laravel学習中の初心者が本当によくやるミスです。
php artisan make:model Post -m のように -m オプションを付けてモデルとマイグレーションを同時に作成し、作成後は必ず php artisan migrate までワンセットで実行する癖をつけると防ぎやすくなります。
よくあるつまずきポイント④：Class not found エラー
症状：Class "App\Models\Xxx" not found
自分で作ったはずのクラスが見つからない、というエラーです。
原因の多くは、Composerのオートロード情報が古いままになっていることです。
✅ 対処法
composer dump-autoload
このコマンドを実行すると、Composerがプロジェクト内のクラスファイルを再スキャンし、オートロード用の情報を作り直してくれます。
特に、ファイルを手動でコピーして新しいクラスを作った直後や、namespace を書き換えた直後に発生しやすいエラーなので、覚えておくと役立ちます。
まとめ
この記事のポイント
- Laravelのエラー画面（Ignition）は、メッセージ→該当ファイル・行数→スタックトレースの順に読むと原因を追いやすい
- ルーティングの変更が反映されないときは、まず
php artisan route:clearを疑う（キャッシュが原因の定番トラブル） .envの変更が反映されないときはphp artisan config:clearも併せて確認するSQLSTATE系のエラーはデータベース未作成・マイグレーション未実行が原因のことが多いClass not foundはcomposer dump-autoloadで解決することが多い
次に読むべき記事
次回は、実践Tipsの中でも特に相談の多い「ファイルアップロード」の実装パターンをまとめて紹介します。
→ 次の記事：ファイルアップロードの実装パターン集
