This page targets Laravel 13 and Framework
v13.42.0. It covers how retry settings combine and which one takes precedence, not basic queue usage.Separate attempt counts from retry deadlines
In Laravel, an “attempt” is not only a successful call tohandle(). Unhandled exceptions, release(), releases by middleware such as WithoutOverlapping or RateLimited, and timeouts also consume attempts. If you specify nothing, the worker tries the job only once.
Tries: cap the number of attempts
You can declare a per-job limit with the Tries attribute. The job’s setting takes precedence over the worker’s --tries.
tries() method. This method takes precedence over the Tries attribute.
RetryFor: set a time window
To limit retries by the time since the job was queued rather than by count, use RetryFor. A bare positional argument is a number of seconds, and you can also pass minutes and hours as named arguments.
RetryFor records the retry deadline in the job payload. The worker does not start new attempts of a job past that deadline. If the job has a retryUntil() method or a retryUntil property, it takes precedence over RetryFor. For a job where retryUntil is in effect, the time-based deadline also takes precedence over Tries.
retryUntil() suits cases where the deadline depends on the job itself, such as when an external service is expected to recover or a business cutoff.
Limit unhandled exceptions
Sometimes you want to keep allowing manualrelease() calls and releases while waiting for a lock, but fail quickly when unhandled exceptions keep happening. In that case, specify Tries and MaxExceptions separately.
MaxExceptions does not count retries caused by release().
By default, attempts where the process crashed (for example from running out of memory) do not count toward the MaxExceptions exception count. If crashes should also count as exceptions, add CountCrashesAsExceptions.
Set the retry interval
A job that throws an exception is normally released back onto the queue. You can set the wait before the next attempt with theBackoff attribute or the backoff() method.
Fixed interval
backoff(). backoff() takes precedence over the Backoff attribute.
--backoff is used.
Release waiting jobs with the same backoff
To run a job again later without throwing an exception, for example when an external API reports that processing is still in progress, usereleaseUsingBackoff(). It releases the job using the value from the job’s backoff array that matches the current attempt. Once the values are exhausted, the last value is used, and without a backoff the job is released immediately.
releaseUsingBackoff() serve different purposes.
- On exception: the job could not be processed, so Laravel releases it using the backoff.
- Manual release: processing itself is fine, but the job runs again later once the external state changes.
releaseUsingBackoff() comes from the job’s Backoff or backoff(). To set a different wait explicitly for a manual release, use release(seconds).
Combined example
The following job retries for at most one hour and tolerates up to 3 unhandled exceptions. On exceptions and on manual releases while waiting for payment, it uses intervals of 10, 30 and 60 seconds.RetryFor is present, the worker uses the deadline rather than Tries(25) as the normal attempt limit. If you specify both, decide whether the time-based deadline or the count-based limit is the primary rule, and lock that intent in with tests. MaxExceptions applies separately from either one.
Precedence of settings
When you mix job and worker settings, the following precedence makes decisions easier.
When a deadline from
retryUntil or RetryFor exists, the worker gives it precedence over the tries count. When you use RetryFor and retryUntil() together, the dynamic retryUntil() wins.
How to choose
- If the deadline for waiting on an external service to recover is clear, use
RetryFor. If the deadline is decided at runtime, useretryUntil(). - For API rate limits and payment status checks, use
BackoffandreleaseUsingBackoff(). - To tolerate many temporary lock waits but few real exceptions, combine
TriesandMaxExceptions. - For work where retries repeat side effects, design idempotency and duplicate control on the external API side, not just the attempt count.
You can also specify
Tries and RetryFor on queued event listeners and notifications. Check that the payload of the target you use carries the same retry contract.Reference links
- Laravel documentation: Max job attempts and timeout
- Laravel documentation: Time-based attempts
- Laravel documentation: Manually releasing a job and
releaseUsingBackoff - Laravel documentation: Backoff for failed jobs
RetryForattributeBackoff,TriesandMaxExceptionsattributesQueue::getJobExpirationInteractsWithQueue::releaseUsingBackoff