Failed job handling in Laravel - Step-by-Step Execution

Concept Flow - Failed job handling

Job dispatched

↓

Job runs

↓

Job success?

No→Job fails

↓

Job recorded in failed_jobs table

↓

Job done

↓

Admin retries or inspects

↓

Job re-dispatched or fixed

This flow shows how Laravel handles a job that fails during execution by recording it and allowing retry or inspection.

Execution Sample

Laravel

<?php
dispatch(new ProcessOrder($order));
// Job runs
// If fails, Laravel logs failure
// Admin can retry failed jobs

This code dispatches a job; if it fails, Laravel logs it for later retry or inspection.

Execution Table

Step	Action	Job Status	Database Table	Next Step
1	Job dispatched	Pending	None	Job runs
2	Job starts running	Running	None	Check success
3	Job fails during execution	Failed	failed_jobs	Record failure
4	Failure recorded in failed_jobs table	Failed	failed_jobs	Admin inspects or retries
5	Admin retries job (deletes record)	Pending	None	Job runs again
6	Job succeeds after retry	Succeeded	None	Process complete
7	No failed job record remains	Succeeded	None	Process complete

💡 Record removed from failed_jobs on retry; job succeeds, ending the failure handling cycle.

Variable Tracker

Variable	Start	After Step 2	After Step 3	After Step 5	Final
Job Status	Pending	Running	Failed	Pending	Succeeded
failed_jobs table	Empty	Empty	Has failure record	Empty	Empty

Key Moments - 3 Insights

Why does the job status change to 'Failed' even though the job code is still running?

When the job encounters an error or exception, Laravel marks it as 'Failed' immediately and records it in the failed_jobs table (see execution_table step 3). This happens before the job fully stops.

What happens to the failed job record after a successful retry?

Upon retrying, Laravel removes the job record from the failed_jobs table (see execution_table step 5), then dispatches a new job instance.

Can a failed job be retried multiple times?

Yes, the admin can retry failed jobs multiple times. Each retry sets the job status back to 'Pending' and reruns it (see execution_table step 5).

Visual Quiz - 3 Questions

Look at the execution table, what is the job status at step 3?

A Pending

B Running

C Failed

D Succeeded

💡 Hint

Check the 'Job Status' column at step 3 in the execution_table.

At which step does Laravel record the failure in the failed_jobs table?

A Step 2

B Step 3

C Step 5

D Step 7

💡 Hint

Look at the 'Database Table' column in the execution_table to see when failed_jobs is updated.

If the admin never retries the failed job, what will be the final job status?

A Failed

B Succeeded

C Pending

D Removed

💡 Hint

Refer to the variable_tracker for 'Job Status' after step 3 and no retry steps.

Concept Snapshot

Laravel Failed Job Handling:
- Dispatch job with dispatch(new JobClass)
- If job fails, Laravel logs it in failed_jobs table
- Admin can inspect and retry failed jobs
- Retry deletes record from failed_jobs and reruns
- Keeps app reliable by tracking failures

Full Transcript

In Laravel, when you dispatch a job, it runs in the background. If the job runs successfully, it finishes quietly. But if something goes wrong, Laravel marks the job as failed and records it in a special database table called failed_jobs. This lets you see which jobs failed and why. You can then retry these failed jobs manually or automatically. When you retry, Laravel removes the record from the failed_jobs table and dispatches the job to run again. This process helps keep your app reliable by tracking and managing background job failures.

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