> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Queue job retry policies

> Combine Tries, RetryFor, MaxExceptions and Backoff to design when, how many times and at what interval Laravel 13 queue jobs are retried.

When you design retries for a queue job, think about four separate questions: how many times to try, until when to try, how many exceptions to tolerate, and how many seconds to wait before the next attempt. In Laravel 13 you can declare each of these with job attributes and methods.

> [!NOTE]
>
> 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.

| What to decide | Attribute / method | Main use |
| - | - | - |
| Maximum attempts | `#[Tries]` / `tries()` | Cap the number of attempts |
| Retry deadline | `#[RetryFor]` / `retryUntil()` | Only try within a time window after dispatch |
| Unhandled exception limit | `#[MaxExceptions]` | Fail after a set number of exceptions |
| Retry interval | `#[Backoff]` / `backoff()` | Set the wait after an exception or a manual release |

## Separate attempt counts from retry deadlines

In Laravel, an "attempt" is not only a successful call to `handle()`. 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`.

```php theme={null}
<?php

namespace App\Jobs;

use Illuminate\Queue\Attributes\Tries;

#[Tries(5)]
class ProcessInvoice implements ShouldQueue
{
    // ...
}
```

To decide the limit from runtime conditions, use the `tries()` method. This method takes precedence over the `Tries` attribute.

```php theme={null}
public function tries(): int
{
    return $this->invoice->isLarge() ? 10 : 3;
}
```

### `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.

```php theme={null}
use Illuminate\Queue\Attributes\RetryFor;

#[RetryFor(hours: 1)]
class ProcessInvoice implements ShouldQueue
{
    // ...
}
```

The following declarations express seconds, minutes and hours respectively.

```php theme={null}
#[RetryFor(90)]
#[RetryFor(minutes: 10)]
#[RetryFor(hours: 4)]
#[RetryFor(hours: 1, minutes: 30)]
```

`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`.

```php theme={null}
use DateTime;

public function retryUntil(): DateTime
{
    return now()->plus(minutes: 30);
}
```

`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 manual `release()` calls and releases while waiting for a lock, but fail quickly when unhandled exceptions keep happening. In that case, specify `Tries` and `MaxExceptions` separately.

```php theme={null}
use Illuminate\Queue\Attributes\MaxExceptions;
use Illuminate\Queue\Attributes\Tries;

#[Tries(25)]
#[MaxExceptions(3)]
class ProcessInvoice implements ShouldQueue
{
    public function handle(): void
    {
        // Allow retries via release(),
        // but fail after 3 unhandled exceptions.
    }
}
```

In this example the job can be attempted up to 25 times. However, after 3 unhandled exceptions it fails even if it has not reached the attempt limit. `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`.

```php theme={null}
use Illuminate\Queue\Attributes\CountCrashesAsExceptions;
use Illuminate\Queue\Attributes\MaxExceptions;

#[CountCrashesAsExceptions]
#[MaxExceptions(3)]
class ProcessInvoice implements ShouldQueue
{
    // ...
}
```

## 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 the `Backoff` attribute or the `backoff()` method.

### Fixed interval

```php theme={null}
use Illuminate\Queue\Attributes\Backoff;

#[Backoff(10)]
class ProcessInvoice implements ShouldQueue
{
    // Wait 10 seconds after an unhandled exception before retrying.
}
```

Pass an array to use a different interval for each attempt. Once the array is exhausted, the last value is used.

```php theme={null}
#[Backoff([10, 30, 60])]
class ProcessInvoice implements ShouldQueue
{
    // Wait 10 seconds before the 1st retry, 30 before the 2nd,
    // and 60 before the 3rd and later.
}
```

To vary the interval by condition, use `backoff()`. `backoff()` takes precedence over the `Backoff` attribute.

```php theme={null}
public function backoff(): int|array
{
    return $this->invoice->isFromExternalProvider()
        ? [30, 60, 300]
        : [5, 15, 30];
}
```

When the job specifies nothing, the worker's `--backoff` is used.

```shell theme={null}
php artisan queue:work redis --tries=3 --backoff=10
```

## 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, use `releaseUsingBackoff()`. 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.

```php theme={null}
<?php

namespace App\Jobs;

use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;
use Illuminate\Queue\Attributes\Backoff;

#[Backoff([10, 30, 60])]
class CheckPaymentStatus implements ShouldQueue
{
    use Queueable;

    public function handle(): void
    {
        if ($this->paymentIsPending()) {
            $this->releaseUsingBackoff();

            return;
        }

        // Work after the payment completes
    }

    private function paymentIsPending(): bool
    {
        // Check the payment service status.
        return true;
    }
}
```

Automatic release on exception and manual release with `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.

The wait for `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.

```php theme={null}
<?php

namespace App\Jobs;

use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;
use Illuminate\Queue\Attributes\Backoff;
use Illuminate\Queue\Attributes\MaxExceptions;
use Illuminate\Queue\Attributes\RetryFor;
use Illuminate\Queue\Attributes\Tries;

#[Tries(25)]
#[RetryFor(hours: 1)]
#[MaxExceptions(3)]
#[Backoff([10, 30, 60])]
class ProcessInvoice implements ShouldQueue
{
    use Queueable;

    public function handle(): void
    {
        // Call the external service to process the invoice.
    }
}
```

When `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.

| Target | Setting that wins | Fallback |
| - | - | - |
| Maximum attempts | `tries()` | `#[Tries]`, `queue:work --tries` |
| Retry deadline | `retryUntil` method / property | `#[RetryFor]` |
| Unhandled exception limit | `#[MaxExceptions]` | No limit when unset |
| Backoff after an exception | `backoff()` | `#[Backoff]`, `queue:work --backoff` |
| Wait for a manual release | Job settings via `releaseUsingBackoff()` | `release(seconds)` |

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

```mermaid theme={null}
flowchart TD
    A["Decide the retry conditions"] --> B{"Stop by count?"}
    B -->|Yes| C["#[Tries]"]
    B -->|No| D["#[RetryFor] or retryUntil()"]
    C --> E{"Fail early only on unhandled exceptions?"}
    D --> E
    E -->|Yes| F["#[MaxExceptions]"]
    E -->|No| G["Not needed"]
    F --> H{"Change the wait time?"}
    G --> H
    H -->|Yes| I["#[Backoff] / backoff()"]
    H -->|Waiting on state| J["releaseUsingBackoff()"]
    H -->|No| K["Worker defaults"]
```

* If the deadline for waiting on an external service to recover is clear, use `RetryFor`. If the deadline is decided at runtime, use `retryUntil()`.
* For API rate limits and payment status checks, use `Backoff` and `releaseUsingBackoff()`.
* To tolerate many temporary lock waits but few real exceptions, combine `Tries` and `MaxExceptions`.
* For work where retries repeat side effects, design idempotency and duplicate control on the external API side, not just the attempt count.

> [!NOTE]
>
> 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](https://github.com/laravel/docs/blob/13.x/queues.md#max-job-attempts-and-timeout)
* [Laravel documentation: Time-based attempts](https://github.com/laravel/docs/blob/13.x/queues.md#time-based-attempts)
* [Laravel documentation: Manually releasing a job and `releaseUsingBackoff`](https://github.com/laravel/docs/blob/13.x/queues.md#manually-releasing-a-job)
* [Laravel documentation: Backoff for failed jobs](https://github.com/laravel/docs/blob/13.x/queues.md#dealing-with-failed-jobs)
* [`RetryFor` attribute](https://github.com/laravel/framework/blob/v13.42.0/src/Illuminate/Queue/Attributes/RetryFor.php)
* [`Backoff`, `Tries` and `MaxExceptions` attributes](https://github.com/laravel/framework/tree/v13.42.0/src/Illuminate/Queue/Attributes)
* [`Queue::getJobExpiration`](https://github.com/laravel/framework/blob/v13.42.0/src/Illuminate/Queue/Queue.php)
* [`InteractsWithQueue::releaseUsingBackoff`](https://github.com/laravel/framework/blob/v13.42.0/src/Illuminate/Queue/InteractsWithQueue.php)


## Related topics

- [Queues](https://kawax.biz/en/queues.md)
- [Queue Job Execution Control](https://kawax.biz/en/advanced/queue-job-control.md)
- [Package queued jobs and upgrade compatibility](https://kawax.biz/en/advanced/package-queue-jobs.md)
- [September 2026 Laravel updates](https://kawax.biz/en/blog/changelog/202609.md)
- [Laravel Horizon](https://kawax.biz/en/horizon.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.