Job retries and failure in Laravel

Introduction

Sometimes jobs in Laravel fail or need to be tried again. Job retries help automatically try a job again if it fails. Handling failures lets you manage what happens when retries stop.

When sending emails that might fail due to temporary network issues.

When processing payments that could fail and need retrying.

When importing data from an external API that might be temporarily down.

When running background tasks that should not stop on first error.

When you want to log or notify when a job finally fails after retries.

Syntax

Laravel

class ExampleJob implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public $tries = 5; // Number of retry attempts
    public $timeout = 120; // Max seconds before job times out

    public function handle()
    {
        // Job logic here
    }

    public function failed(Exception $exception)
    {
        // Logic when job fails after all retries
    }
}

The $tries property sets how many times Laravel will retry the job before failing.

The failed() method runs only after all retries fail, letting you handle cleanup or notifications.

Examples

This job will try 3 times before calling failed().

Laravel

class SendEmailJob implements ShouldQueue
{
    public $tries = 3;

    public function handle()
    {
        // Send email logic
    }

    public function failed(Exception $exception)
    {
        // Notify admin about failure
    }
}

This job will not retry and will call failed() immediately on failure.

Laravel

class ProcessPaymentJob implements ShouldQueue
{
    public $tries = 1; // No retries

    public function handle()
    {
        // Payment processing
    }

    public function failed(Exception $exception)
    {
        // Log failure
    }
}

Setting $tries = null means Laravel will keep retrying forever until success.

Laravel

class ImportDataJob implements ShouldQueue
{
    public $tries = null; // Infinite retries (not recommended)

    public function handle()
    {
        // Data import
    }
}

Sample Program

This example simulates a job that always fails. It tries 3 times, printing each attempt. After the last failure, it calls the failed() method to show the final failure message.

Laravel

<?php

namespace App\Jobs;

use Exception;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;

class ExampleJob implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public $tries = 3;

    public function handle()
    {
        echo "Trying job...\n";
        // Simulate failure
        throw new Exception("Job failed");
    }

    public function failed(Exception $exception)
    {
        echo "Job failed after retries: " . $exception->getMessage() . "\n";
    }
}

// Simulate running the job manually for demonstration
$job = new ExampleJob();

for ($attempt = 1; $attempt <= $job->tries; $attempt++) {
    try {
        echo "Attempt $attempt:\n";
        $job->handle();
        break; // If success, stop retrying
    } catch (Exception $e) {
        echo "Caught exception: " . $e->getMessage() . "\n";
        if ($attempt === $job->tries) {
            $job->failed($e);
        }
    }
}

Important Notes

Time complexity: Job retries depend on external factors, but each retry runs the job logic once.

Space complexity: Minimal, mostly storing job data and retry count.

Common mistake: Forgetting to set $tries means Laravel uses default retries, which might be unexpected.

Use retries when failures are temporary. Use failed() to handle permanent failures like logging or alerts.

Summary

Set $tries in your job to control retry attempts.

Use the failed() method to handle what happens after all retries fail.

Retries help jobs recover from temporary problems without manual intervention.