Job retries and error handling in Ruby on Rails - Step-by-Step Execution

Concept Flow - Job retries and error handling

Job Enqueued

↓

Job Starts Running

↓

Job Succeeds?

No→Error Raised

↓

Retry Count < Max?

No→Job Fails Permanently

↓

Job Completes

↓

Job Re-enqueued with Delay

↓

Job Starts Running

This flow shows how a job runs, checks for success, and if it fails, retries up to a limit before failing permanently.

Execution Sample

Ruby on Rails

class MyJob < ApplicationJob
  retry_on StandardError, wait: 5.seconds, attempts: 3

  def perform
    do_something_risky
  end
end

A job that retries up to 3 times with 5 seconds wait if a StandardError occurs.

Execution Table

Step	Action	Retry Count	Error Raised	Job Status	Next Step
1	Job starts running	0	No	Success	Job completes
2	Job starts running	0	Yes (StandardError)	Failed	Check retry count
3	Retry count 0 < 3	0	Yes	Retry scheduled	Job re-enqueued after 5s
4	Job starts running	1	Yes (StandardError)	Failed	Check retry count
5	Retry count 1 < 3	1	Yes	Retry scheduled	Job re-enqueued after 5s
6	Job starts running	2	Yes (StandardError)	Failed	Check retry count
7	Retry count 2 < 3	2	Yes	Retry scheduled	Job re-enqueued after 5s
8	Job starts running	3	Yes (StandardError)	Failed	Check retry count
9	Retry count 3 < 3	3	Yes	No	Job fails permanently

💡 Job fails permanently after 3 retries because retry count reached max attempts.

Variable Tracker

Variable	Start	After 1	After 2	After 3	Final
retry_count	0	1	2	3	3
job_status	pending	failed	failed	failed	failed
error_raised	no	yes	yes	yes	yes

Key Moments - 3 Insights

Why does the job retry only 3 times and then stop?

Because the retry_on option sets attempts: 3, so after 3 retries (see execution_table rows 3,5,7), the job stops retrying and fails permanently (row 9).

What happens if the job succeeds on a retry?

If no error is raised during perform (row 1), the job completes successfully and does not retry again.

Why is there a wait time before retrying?

The wait: 5.seconds option delays the retry to avoid immediate repeated failures, giving time for transient issues to resolve (see rows 3,5,7 where retry is scheduled after delay).

Visual Quiz - 3 Questions

Look at the execution table, what is the retry_count when the job fails permanently?

A 0

B 2

C 3

D 4

💡 Hint

Check the retry_count column in the last row of the execution_table.

At which step does the job first get re-enqueued for retry?

A Step 3

B Step 2

C Step 1

D Step 9

💡 Hint

Look at the Next Step column where retry is scheduled after failure.

If the wait time was removed, how would the execution_table change?

A Job would never retry

B Retries would happen immediately without delay

C Retry count would reset to zero

D Job would succeed automatically

💡 Hint

Consider the effect of wait: 5.seconds on retry scheduling in the execution_table.

Concept Snapshot

Job retries in Rails use retry_on with options like attempts and wait.
If perform raises an error, job retries up to attempts times.
Each retry waits the specified delay before running again.
If retries exceed attempts, job fails permanently.
Successful perform ends retries immediately.

Full Transcript

This visual execution trace shows how Rails jobs handle retries and errors. When a job runs, if it succeeds, it completes immediately. If it raises a StandardError, Rails checks if the retry count is less than the maximum attempts. If yes, it schedules a retry after a wait time (5 seconds here). This repeats until the retry count reaches the max attempts (3). After that, the job fails permanently and stops retrying. Variables like retry_count and job_status update accordingly. This helps handle transient errors gracefully by retrying jobs a few times before giving up.