メインコンテンツへスキップ
キュージョブの再試行を設計するときは、「何回試すか」「いつまで試すか」「例外を何回許容するか」「次の試行まで何秒待つか」を分けて考えます。Laravel 13では、これらをジョブの Attribute とメソッドで宣言できます。
このページはLaravel 13とFramework v13.42.0を対象にしています。基本的なキューの使い方ではなく、再試行設定の組み合わせと優先順位を扱います。

試行回数と再試行期限を分ける

Laravelの「試行」は handle() が正常に呼び出された回数だけではありません。未処理例外、release()、WithoutOverlapping や RateLimited などのミドルウェアによる解放、タイムアウトも試行を消費します。何も指定しなければ、ワーカーはジョブを1回だけ試します。

Tries — 回数を上限にする

ジョブごとの上限を Tries Attribute で宣言できます。ワーカーの --tries よりジョブ側の指定が優先されます。
実行時の条件から上限を決める場合は tries() メソッドを使います。このメソッドは Tries Attribute より優先されます。

RetryFor — 時間枠を指定する

回数ではなく、キューへ投入されてから再試行できる時間を指定するには RetryFor を使います。引数なしの位置引数は秒数で、minutes と hours を名前付き引数で指定することもできます。
次の指定はそれぞれ秒・分・時間を表します。
RetryFor はジョブのペイロードに再試行期限を記録します。ワーカーはその期限を過ぎたジョブを新たに実行しません。retryUntil() メソッド、または retryUntil プロパティがある場合は、そちらが RetryFor より優先されます。また、retryUntil が有効なジョブでは Tries より時間による期限が優先されます。
retryUntil() は、外部サービスの復旧時刻や業務上の締め切りなど、ジョブの内容から期限を動的に決める場合に向いています。

未処理例外の上限を決める

手動の release() やロック取得待ちの解放は続けたい一方で、未処理例外が続いた場合は早く失敗させたいことがあります。その場合は Tries と MaxExceptions を分けて指定します。
この例では、ジョブは最大25回まで試行できます。ただし、未処理例外が3回発生すると、試行回数の上限に達していなくても失敗します。MaxExceptions は、release() による再試行の回数を数えるための設定ではありません。 プロセスがメモリ不足などでクラッシュした試行は、デフォルトでは MaxExceptions の例外数に含まれません。クラッシュも例外として数える必要がある場合は、CountCrashesAsExceptions を追加します。

再試行間隔を設定する

例外が発生したジョブは、通常、再びキューへ解放されます。次の試行までの待ち時間は Backoff Attribute または backoff() メソッドで設定できます。

固定の間隔

配列を指定すると、試行ごとに異なる間隔を設定できます。配列の要素を使い切った後は最後の値が使われます。
条件に応じて間隔を変える場合は backoff() を使います。backoff() は Backoff Attribute より優先されます。
ジョブごとの指定がない場合は、ワーカーの --backoff が使われます。

待機中のジョブを同じバックオフで解放する

外部APIが「処理中」を返したときなど、例外を投げずにジョブを後で再実行したい場合は releaseUsingBackoff() を使います。ジョブに設定したバックオフ配列のうち、現在の試行に対応する値で解放します。値を使い切った場合は最後の値が使われ、バックオフがなければ即時解放されます。
例外時の自動解放と、releaseUsingBackoff() による手動解放は目的が異なります。
  • 例外時:ジョブが処理できなかったため、Laravelがバックオフを使って解放する。
  • 手動解放:処理自体は正常だが、外部状態が変わるまで後で再実行する。
releaseUsingBackoff() の待ち時間はジョブの Backoff または backoff() を参照します。手動解放で別の待ち時間を明示したい場合は、release(秒数) を使います。

組み合わせの例

次のジョブは、最大1時間だけ再試行し、未処理例外は3回まで許容します。例外時または決済待ちの手動解放では、10秒・30秒・60秒の間隔を使います。
RetryFor がある場合、ワーカーは Tries(25) ではなく期限を基準に通常の試行上限を判断します。両方を指定するなら、時間による期限を主軸にするのか、回数による上限を主軸にするのかを決め、意図をテストで固定します。MaxExceptions はそのどちらとも別に適用されます。

設定の優先順位

ジョブとワーカーの設定を混在させるときは、次の優先順位で考えると判断しやすくなります。 retryUntil または RetryFor による期限がある場合、ワーカーは tries の回数より期限を優先します。RetryFor と retryUntil() を同時に使う場合は、動的な retryUntil() が優先されます。

選び方

  • 外部サービスの復旧を待つ期限が明確なら RetryFor、期限が実行時に決まるなら retryUntil()。
  • APIのレート制限や決済状態の確認には Backoff と releaseUsingBackoff()。
  • 一時的なロック待ちを多く許容し、実際の例外は少なくしたいなら Tries と MaxExceptions を組み合わせる。
  • 再試行が副作用を重ねる処理では、試行回数だけでなく冪等性と外部API側の重複制御も設計する。
Tries と RetryFor は、キューに入るイベントリスナーや通知にも指定できます。利用する対象のペイロードが同じ再試行契約を持つことを確認してください。

参考リンク

最終更新日 2026年11月16日