Job retries and failure in Laravel - Step-by-Step Execution

Concept Flow - Job retries and failure

Job dispatched

↓

Job runs

↓

Job succeeds?

No→Job fails

↓

Retries left?

No→Mark job as failed

↓

Retry job after delay

↓

Job runs again

This flow shows how a Laravel job runs, checks success, retries if it fails and retries remain, or marks as failed if no retries left.

Execution Sample

Laravel

public function handle()
{
    // Job logic here
    if ($this->attempts() >= 3) {
        return; // Job succeeds after 3 attempts
    }
    throw new \Exception('Fail to retry');
}

This job throws an exception to fail and retry up to 3 times before succeeding.

Execution Table

Step	Action	Attempt Number	Result	Next Step
1	Job dispatched and runs	1	Fails (exception thrown)	Check retries left
2	Retries left? (1 < 3)	1	Yes	Retry job after delay
3	Job runs again	2	Fails (exception thrown)	Check retries left
4	Retries left? (2 < 3)	2	Yes	Retry job after delay
5	Job runs again	3	Fails (exception thrown)	Check retries left
6	Retries left? (3 < 3)	3	No	Mark job as failed
7	Job marked as failed	3	Failure recorded	Stop retries

💡 Retries exhausted at attempt 3, job marked as failed and stops retrying.

Variable Tracker

Variable	Start	After 1	After 2	After 3	Final
attempts()	0	1	2	3	3
Job status	pending	failed	failed	failed	failed

Key Moments - 3 Insights

Why does the job retry only up to 3 times and then fail?

Because the attempts() method returns the current try count, and when it reaches 3, the condition to retry is false (see execution_table rows 6 and 7).

What happens if the job succeeds before reaching max retries?

The job stops retrying and is considered successful, so no further retries or failure marking occur (not shown in this trace but implied by the success branch in concept_flow).

How does Laravel know when to mark a job as failed?

When the retry limit is reached and the job still fails, Laravel marks it as failed automatically (see execution_table row 7).

Visual Quiz - 3 Questions

Look at the execution table, what is the attempt number when the job is marked as failed?

A 1

B 3

C 2

D 4

💡 Hint

Check the 'Attempt Number' column in the row where 'Job marked as failed' occurs.

At which step does the job decide not to retry anymore?

A Step 4

B Step 2

C Step 6

D Step 7

💡 Hint

Look for the step where 'Retries left?' condition is false in the execution_table.

If the max retries were increased to 5, how would the execution table change?

A The job would retry up to attempt 5 before failing

B The job would fail immediately at attempt 3

C The job would never fail

D The job would succeed on first try

💡 Hint

Refer to the retry condition check in execution_table rows 2, 4, and 6.

Concept Snapshot

Laravel jobs run and may fail.
If a job fails, Laravel retries it up to a max attempts limit.
Each retry waits some delay before running again.
When retries are exhausted, Laravel marks the job as failed.
Use attempts() to check current try count inside the job.
Throw exceptions to trigger retries automatically.

Full Transcript

In Laravel, when a job is dispatched, it runs and may succeed or fail. If it fails, Laravel checks if the job has retries left by comparing the current attempt count with the max allowed. If retries remain, Laravel waits and retries the job. This repeats until the job succeeds or the retry limit is reached. When no retries remain, Laravel marks the job as failed and stops retrying. The attempts() method inside the job returns how many times the job has run. Throwing an exception causes the job to fail and trigger a retry if allowed. This process helps handle temporary failures gracefully by retrying jobs automatically.

Practice

1. In Laravel, what does setting the $tries property in a job class control?

easy

A. The number of times the job will be retried if it fails

B. The maximum execution time of the job

C. The priority of the job in the queue

D. The database connection used by the job

Solution

1. Step 1: Understand the role of $tries in Laravel jobs

   The $tries property defines how many times Laravel will attempt to run the job if it fails.

2. Step 2: Differentiate from other job properties

   It does not control execution time, priority, or database connection, only retry attempts.

3. Final Answer:

   The number of times the job will be retried if it fails -> Option A

4. Quick Check:

   $tries controls retry attempts [OK]

Hint: Remember: $tries means retry count for failed jobs [OK]

Common Mistakes:

• Confusing $tries with job timeout
• Thinking $tries sets job priority
• Assuming $tries controls database connection

2. Which of the following is the correct way to define a job retry limit of 5 attempts in a Laravel job class?

easy

A. public $tries = 5;

B. protected $retry = 5;

C. public $retryAttempts = 5;

D. protected $triesCount = 5;

Solution

1. Step 1: Recall the correct property name for retry attempts

   Laravel uses $tries as a public property to set retry limits.

2. Step 2: Check syntax and visibility

   The property should be public and named exactly $tries to work properly.

3. Final Answer:

   public $tries = 5; -> Option A

4. Quick Check:

   Correct property is public $tries [OK]

Hint: Use public $tries = number; to set retries [OK]

Common Mistakes:

• Using protected instead of public
• Using wrong property names like $retry or $triesCount
• Confusing retry limit with timeout

3. Given this Laravel job class snippet:

class SendEmailJob implements ShouldQueue {
    public $tries = 3;
    public function handle() {
        // code that may fail
        throw new \Exception('Failed');
    }
    public function failed() {
        // handle failure
        Log::info('Job failed permanently');
    }
}

How many times will Laravel attempt to run this job before calling failed()?

medium

A. 1 time

B. 3 times

C. 4 times

D. It will retry indefinitely

Solution

1. Step 1: Understand how $tries works

   The $tries property sets the maximum number of times the job will be attempted, including the initial attempt.

2. Step 2: Calculate total attempts

   With $tries = 3, Laravel attempts the job 3 times total before calling failed().

3. Final Answer:

   3 times -> Option B

4. Quick Check:

   Total attempts = $tries = 3 [OK]

Hint: Total attempts = $tries [OK]

Common Mistakes:

• Thinking total attempts = 1 + $tries
• Assuming retries are unlimited
• Confusing failed() call timing

4. Examine this Laravel job code:

class ProcessOrder implements ShouldQueue {
    public $tries = 2;
    public function handle() {
        // some code
        throw new \Exception('Error');
    }
    public function failed() {
        // log failure
        Log::error('Order processing failed');
    }
}

Why might the failed() method never be called after job failures?

medium

A. Because the $tries property is set to 2, so it retries infinitely

B. Because the job is not implementing the ShouldQueue interface

C. Because the job is failing but failed() is not triggered until retries are exhausted

D. Because the failed() method must accept an Exception parameter

Solution

1. Step 1: Check method signature for failed()

   Laravel expects failed() to accept an Exception parameter to receive failure details.

2. Step 2: Understand impact of missing parameter

   If failed() lacks the Exception parameter, Laravel may not call it properly after retries.

3. Final Answer:

   The failed() method must accept an Exception parameter -> Option D

4. Quick Check:

   failed(Exception $exception) required [OK]

Hint: Add Exception parameter to failed() method [OK]

Common Mistakes:

• Assuming $tries = 2 means infinite retries
• Forgetting to implement ShouldQueue interface
• Ignoring method signature requirements

5. You want a Laravel job to retry 3 times on failure, but after the last failure, you want to notify the user by email. Which is the best way to implement this behavior?

hard

A. Set public $tries = 3; and use a separate job to send the email without failed()

B. Set public $tries = 3; and send the email inside the handle() method after catching exceptions

C. Set public $tries = 3; and define a failed(Exception $exception) method to send the email notification

D. Set public $maxAttempts = 3; and send the email in the constructor

Solution

1. Step 1: Use $tries to limit retry attempts

   Setting public $tries = 3; ensures the job retries 3 times on failure.

2. Step 2: Use failed(Exception $exception) to handle final failure

   Defining failed() with the Exception parameter allows sending email after all retries fail.

3. Final Answer:

   Set public $tries = 3; and define a failed(Exception $exception) method to send the email notification -> Option C

4. Quick Check:

   Retries + failed() method for final failure handling [OK]

Hint: Use $tries and failed(Exception $exception) for retries and notification [OK]

Common Mistakes:

• Trying to send email inside handle() ignoring retries
• Using wrong property name like $maxAttempts
• Not using failed() method for final failure