Failed job handling in Laravel

Introduction

Failed job handling helps you know when a background task did not finish correctly. It lets you fix problems without losing data.

When a queued email fails to send and you want to retry later.

When processing a payment in the background fails and you need to log the error.

When importing large data files and some jobs fail, so you can review and retry.

When a notification job crashes and you want to keep track of it.

When you want to alert your team if any background task fails.

Syntax

Laravel

php
// To listen for failed jobs, define a failed() method in your job class
public function failed(Exception $exception)
{
    // Handle the failure, like logging or notifying
}

// To retry failed jobs from the command line:
php artisan queue:retry all

// To delete failed jobs:
php artisan queue:flush

The failed() method runs only if the job fails after all retries.

You can use php artisan queue:failed to list all failed jobs.

Examples

This example shows how to add a failed() method to log errors when the job fails.

Laravel

use Exception;
use Illuminate\Support\Facades\Log;

class SendEmailJob implements ShouldQueue
{
    public function handle()
    {
        // send email logic
    }

    public function failed(Exception $exception)
    {
        // Log the failure or notify admin
        Log::error('Email job failed: ' . $exception->getMessage());
    }
}

This command retries every job that failed before.

Laravel

// Retry all failed jobs from the terminal
php artisan queue:retry all

This command clears the list of failed jobs after you have handled them.

Laravel

// Delete all failed jobs from the terminal
php artisan queue:flush

Sample Program

This job tries to process an order. If the order ID is 0, it throws an error. The failed() method logs the 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;
use Illuminate\Support\Facades\Log;

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

    public $orderId;

    public function __construct(int $orderId)
    {
        $this->orderId = $orderId;
    }

    public function handle()
    {
        // Simulate processing order
        if ($this->orderId === 0) {
            // Simulate failure
            throw new Exception('Invalid order ID');
        }
        // Process order logic here
        Log::info("Order {$this->orderId} processed successfully.");
    }

    public function failed(Exception $exception)
    {
        // Log failure details
        Log::error("Order {$this->orderId} failed: " . $exception->getMessage());
    }
}

// Usage example (not part of the job class):
// dispatch(new ProcessOrderJob(0)); // This will fail and trigger failed() method

Important Notes

Always add a failed() method to handle cleanup or notifications when jobs fail.

Use Laravel's built-in commands to manage failed jobs easily.

Check your queue driver supports failed job storage (like database or Redis).

Summary

Failed job handling helps catch and manage background task errors.

Use the failed() method in job classes to react to failures.

Laravel provides commands to list, retry, and clear failed jobs.

Practice

1. What is the primary purpose of the failed() method in a Laravel job class?

easy

A. To list all failed jobs in the queue

B. To retry a failed job automatically

C. To define actions when a queued job fails during execution

D. To clear all failed jobs from the database

Solution

1. Step 1: Understand the role of failed() method

   The failed() method is a special method in Laravel job classes that runs when the job fails after all retry attempts.

2. Step 2: Identify what failed() does

   This method allows you to define custom logic like sending notifications or logging when a job fails.

3. Final Answer:

   To define actions when a queued job fails during execution -> Option C

4. Quick Check:

   failed() handles failure actions [OK]

Hint: Remember: failed() runs only on job failure [OK]

Common Mistakes:

• Confusing failed() with retry commands
• Thinking it lists or clears failed jobs
• Assuming it runs on successful job completion

2. Which of the following is the correct Artisan command to retry all failed jobs in Laravel?

easy

A. php artisan queue:retry all

B. php artisan queue:retry --all

C. php artisan queue:retry --failed

D. php artisan queue:retry --all-jobs

Solution

1. Step 1: Recall the syntax for retrying failed jobs

   Laravel's command to retry failed jobs is php artisan queue:retry followed by the job IDs or all to retry all.

2. Step 2: Identify the correct option

   The correct command to retry all failed jobs is php artisan queue:retry all.

3. Final Answer:

   php artisan queue:retry all -> Option A

4. Quick Check:

   Retry all failed jobs = queue:retry all [OK]

Hint: Use 'all' after retry to retry every failed job [OK]

Common Mistakes:

• Adding extra flags like --all or --failed which don't exist
• Using incorrect command syntax
• Confusing retry with clear commands

3. Given this Laravel job class snippet, what will happen when the job fails?

class SendEmailJob implements ShouldQueue {
    public function handle() {
        // code that throws an exception
    }
    public function failed(Exception $exception) {
        Log::error('Email sending failed: ' . $exception->getMessage());
    }
}

medium

A. The job will be retried indefinitely without logging

B. The job will succeed despite the exception

C. The job will be removed silently without any action

D. The job failure will be logged with the error message

Solution

1. Step 1: Analyze the failed() method implementation

   The failed() method logs an error message when the job fails due to an exception.

2. Step 2: Understand job failure behavior

   When the job throws an exception, Laravel calls failed() and logs the failure message.

3. Final Answer:

   The job failure will be logged with the error message -> Option D

4. Quick Check:

   failed() logs failure message [OK]

Hint: Check if failed() logs or retries [OK]

Common Mistakes:

• Assuming job retries indefinitely without limit
• Thinking failure is ignored without logging
• Believing job succeeds despite exception

4. Consider this command to clear failed jobs:

php artisan queue:flush

What is the issue with this command?

medium

A. It clears all failed jobs correctly

B. The command does not exist; the correct command is queue:forget

C. It retries all failed jobs instead of clearing

D. It only clears jobs from the default queue, not all queues

Solution

1. Step 1: Verify the correct command to clear failed jobs

   The php artisan queue:flush command does not exist in Laravel. The correct command to remove failed jobs is php artisan queue:forget {id} for specific jobs or manually clearing the failed_jobs table.

2. Step 2: Confirm the issue

   Since queue:flush is not a valid command, it cannot clear failed jobs.

3. Final Answer:

   The command does not exist; the correct command is queue:forget -> Option B

4. Quick Check:

   queue:flush is invalid; use queue:forget [OK]

Hint: Remember: queue:flush is not a valid Artisan command [OK]

Common Mistakes:

• Thinking queue:flush does not exist
• Confusing it with queue:forget for specific jobs
• Mistaking it for a retry command

5. You want to notify the admin by email whenever a job fails in Laravel. Which approach correctly implements this using the failed() method?

hard

A. Add a failed() method in the job class that sends an email notification to the admin

B. Use php artisan queue:notify-admin command after job failure

C. Configure the failed_jobs table to send emails automatically

D. Set notify_admin = true in the job constructor

Solution

1. Step 1: Understand how to handle job failure notifications

   Laravel allows defining a failed() method in job classes to run custom logic on failure, such as sending emails.

2. Step 2: Identify the correct implementation

   Adding a failed() method that sends an email notification to the admin is the correct way to notify on failure.

3. Final Answer:

   Add a failed() method in the job class that sends an email notification to the admin -> Option A

4. Quick Check:

   Use failed() to notify admin on job failure [OK]

Hint: Put notification code inside failed() method [OK]

Common Mistakes:

• Expecting Artisan commands to notify admin automatically
• Assuming database config sends emails
• Trying to set flags in constructor for notifications