Laravelのキューが処理されないときは、ジョブを投入した先と、ワーカーが監視する先を照合します。そのうえで、まだ待っているのか、実行中なのか、失敗しているのかを分けてください。ワーカーを追加したりジョブを再投入したりする前に、すでに動いている処理との重複を確認する必要があります。
この記事はLaravel 13.x、PHP 8.3以上を前提に、主にdatabase・Redis接続を調べるための確認手順です。別の版やAmazon SQSなどでは、保存場所・再配送・タイムアウトの扱いも、その接続方式の公式仕様で確認します。Laravel 13の最低PHPは8.3です。S1
まず「投入されている」と分かる根拠を残す
画面で受付完了になったことだけでは、目的のキューへジョブが入ったと決まりません。確認するのは、実行した操作、ジョブの種類、接続名、キュー名、投入した時刻です。データを共有する際は、ペイロードに含まれる顧客情報を除きます。
| 観測したこと | 次の確認先 |
|---|---|
| 待ち行列に記録が見つからない | 呼び出し経路、接続先、即時実行、遅延や投入条件 |
| 待ち行列に残っている | ワーカーの接続名・キュー名・起動状態 |
| 件数は減ったが結果がない | 実行ログ、失敗記録、外部処理の完了状態 |
| 一度進んでまた止まる | プロセス管理、例外、タイムアウト、負荷 |
database接続のテーブルを見ても、Redis接続へ入れたジョブは確認できません。また、sync は同期実行用の接続で、非同期の待ち行列をワーカーが消化する方式とは違います。ジョブ側の onConnection や onQueue で既定値を上書きしていないかも見ます。S2S7
接続名とキュー名は、別の項目として並べる
QUEUE_CONNECTION は既定のキュー接続の選択に関係します。一方、キュー名は同じ接続内で処理を分けるための名前です。「Redisを使っている」だけでは、同じ待ち行列を見ていることになりません。
たとえば次のように、投入側と実行側を一行ずつ比較します。値は説明用の架空例です。
| 項目 | ジョブの投入側 | ワーカー側 |
|---|---|---|
| 環境・リリース | staging、同じリリース | staging、同じリリース |
| 接続名 | redis | redis |
| キュー名 | reports | default |
| 保存領域 | 検証用Redisの指定領域 | 同じ接続先・領域か確認 |
この場合は、キュー名の不一致が調査対象です。接続名が同じでも、接続するRedisの領域やデータベースが異なれば、別の場所を見ている可能性があります。実値を確認するときも、接続用の認証情報を出力する必要はありません。S2
.env の文字列だけでなく、アプリで有効な設定とワーカーの起動引数を確認してください。設定がキャッシュされている場合、.env を編集しただけでは現在の設定が変わらないことがあります。原因調査として全設定を表示すると秘密情報が混ざるため、必要な値だけを管理者が確認します。S3
キャッシュを消す・再生成する操作は、稼働中アプリへの設定変更です。とりあえず実行するのではなく、現在の設定、変更内容、戻し方を把握したうえで、普段の反映手順に沿って行います。
プロセスが存在するだけで、目的の仕事を処理できるとは限らない
ワーカーについては、起動の有無に加え、作業ディレクトリ、PHPの起動パス、実行ユーザー、接続名、キュー名、終了した場合の再起動方法を確認します。WebのPHPと、常駐プロセスのPHPが異なる構成にも注意してください。
Laravelの queue:work は長く動くプロセスなので、デプロイ後も古いコードや設定で動き続けることがあります。queue:restart は処理中のジョブを終えて終了するよう通知するもので、新しいワーカーを常駐起動するコマンドではありません。プロセス管理の設定と、再起動通知に使うキャッシュの共有も確認が必要です。S5
Supervisor、コンテナの管理機構、Horizonなど、実際に何がワーカーを管理しているかを先に調べます。既存の管理機構を知らずにターミナルから別のワーカーを立ち上げると、調査中にも処理が進み、観測しにくくなります。
一件だけ試すなら、本番と分けた確認用キューを使う
切り分け用にワーカーを動かす場合は、本番と接続しない検証環境を使います。メール、決済、外部API、ファイル保存先も検証用に分離し、副作用のない自作の確認用ジョブ一件だけを用意してください。
次は、検証用の database 接続にある diagnostic キューから、一件を処理するコマンド例です。接続と名前は環境に合わせる必要があります。このコマンドはジョブを実行するため、本番にそのまま貼り付けないでください。S6
php artisan queue:work database --queue=diagnostic --once
--once でも、取り出したジョブの中身は実行されます。読み取り専用の確認ではありません。入力した一件と、実行開始・終了の記録、期待する結果を照合します。
この確認が通っても、通常の接続・キュー・常駐設定まで正常になったとは限りません。確認用だけ成功した場合は、通常運用との差へ戻って調べます。
failed_jobsとログは、実行した時刻と対象で絞る
失敗したジョブを調べるために、公式には次のコマンドがあります。失敗記録に使うデータベース等へ接続できる環境で、許可を得て実行します。S2
php artisan queue:failed
一覧の失敗時刻、接続、キュー、ジョブIDと、その時刻のログを照合します。古い別の失敗を、いま止まっている原因と取り違えないようにしてください。
failed_jobs が空でも、未投入、待機中、実行中、失敗記録の保存を無効化した設定などは区別が必要です。失敗がない証拠にはなりません。ログも storage/logs/laravel.log 固定とは限らず、config/logging.php で選んだチャンネルを確認します。S2S4
タイムアウトを疑う場合は、仕事の所要時間、ワーカーの --timeout、接続の retry_after を別に確認します。後者が再配送に関係する接続では、ワーカーが長く動きすぎると、同じ仕事を別のワーカーが処理し始めるおそれがあります。値を大きくする前に、終了と再配送の関係を公式資料で確認してください。S5
再実行の前に「すでに終わった部分」を確かめる
失敗として記録されても、途中まで行った外部操作が戻っているとは限りません。メール送信後の記録で失敗したケースなら、同じジョブを再実行すると再送になる可能性があります。
再試行する前に、対象の仕事を特定し、原因への対処、既存ワーカーの状態、外部処理の完了状況、同じ入力を二度処理しても問題がない設計かを確認します。queue:retry を使う場合も、対象を絞り、結果を観測してから次へ進めます。最初から全失敗ジョブを一括で再投入する進め方は避けます。S2
DBの更新前にジョブが動いてしまう場合は、トランザクションと after_commit などの投入条件も調べます。ただし、待っているジョブを動かしたいだけなのか、投入の設計を変える必要があるのかは別の判断です。S2
更新後に止まった場合は、Laravel 12から13へ上げる際の実行環境と検証を照合できます。既存コードの読み直しやテストで手が止まる場合は、PHP経験者の学び直し方法から、必要な部分を補う方法もあります。
公式情報の確認日:2026年11月23日。コマンドの引数は公式仕様と照合していますが、実際のLaravelアプリでのワーカー起動・障害再現・ジョブ再試行は行っていません。Mac・Windowsでも、シェルの見た目より、ワーカーが動くサーバーやコンテナの環境を優先して確認します。
出典
- https://laravel.com/docs/13.x/releases Laravel「Release Notes」(確認日: 2026-11-23) ↩1
- https://laravel.com/docs/13.x/queues Laravel「Queues」(確認日: 2026-11-23) ↩1 ↩2 ↩3 ↩4 ↩5 ↩6
- https://laravel.com/docs/13.x/configuration Laravel「Configuration」(確認日: 2026-11-23) ↩1
- https://laravel.com/docs/13.x/logging Laravel「Logging」(確認日: 2026-11-23) ↩1
- https://github.com/laravel/framework/blob/13.x/src/Illuminate/Queue/Worker.php Laravel公式ソース「Worker.php 13.x」(確認日: 2026-11-23) ↩1 ↩2
- https://github.com/laravel/framework/blob/13.x/src/Illuminate/Queue/Console/WorkCommand.php Laravel公式ソース「WorkCommand.php 13.x」(確認日: 2026-11-23) ↩1
- https://github.com/laravel/laravel/blob/13.x/config/queue.php Laravel公式アプリ構成「config/queue.php 13.x」(確認日: 2026-11-23) ↩1