MENU

Laravelのキューが処理されないときの確認方法|接続先・ワーカー・失敗ジョブを照合する

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でも、シェルの見た目より、ワーカーが動くサーバーやコンテナの環境を優先して確認します。

出典

  1. https://laravel.com/docs/13.x/releases Laravel「Release Notes」(確認日: 2026-11-23) ↩1
  2. https://laravel.com/docs/13.x/queues Laravel「Queues」(確認日: 2026-11-23) ↩1 ↩2 ↩3 ↩4 ↩5 ↩6
  3. https://laravel.com/docs/13.x/configuration Laravel「Configuration」(確認日: 2026-11-23) ↩1
  4. https://laravel.com/docs/13.x/logging Laravel「Logging」(確認日: 2026-11-23) ↩1
  5. https://github.com/laravel/framework/blob/13.x/src/Illuminate/Queue/Worker.php Laravel公式ソース「Worker.php 13.x」(確認日: 2026-11-23) ↩1 ↩2
  6. https://github.com/laravel/framework/blob/13.x/src/Illuminate/Queue/Console/WorkCommand.php Laravel公式ソース「WorkCommand.php 13.x」(確認日: 2026-11-23) ↩1
  7. https://github.com/laravel/laravel/blob/13.x/config/queue.php Laravel公式アプリ構成「config/queue.php 13.x」(確認日: 2026-11-23) ↩1
よかったらシェアしてね!
  • URLをコピーしました!
目次