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.

Practice

1. What does the retry_on method do in a Rails Active Job?

easy

A. It retries the job automatically if a specified error occurs.

B. It discards the job immediately without retrying.

C. It schedules the job to run only once without retries.

D. It logs the error but does not retry the job.

Solution

1. Step 1: Understand retry_on purpose

   The retry_on method tells Rails to retry a job if a certain error happens during execution.

2. Step 2: Compare with other options

   Unlike discard_on, which stops retries, retry_on allows automatic retrying.

3. Final Answer:

   It retries the job automatically if a specified error occurs. -> Option A

4. Quick Check:

   retry_on = automatic retry [OK]

Hint: Remember: retry_on means try again on error [OK]

Common Mistakes:

• Confusing retry_on with discard_on
• Thinking retry_on discards the job
• Assuming retry_on logs errors only

2. Which of the following is the correct syntax to retry a job on ActiveRecord::Deadlocked error with 3 attempts in Rails?

easy

A. retry_on(ActiveRecord::Deadlocked, attempts: 3)

B. retry_on ActiveRecord::Deadlocked attempts=3

C. retry_on ActiveRecord::Deadlocked attempts: 3

D. retry_on(ActiveRecord::Deadlocked attempts: 3)

Solution

1. Step 1: Recall method call syntax in Ruby

   Methods with arguments and options require parentheses for clarity, especially with keyword arguments.

2. Step 2: Check each option's syntax

   retry_on(ActiveRecord::Deadlocked, attempts: 3) uses parentheses and correct keyword argument syntax: retry_on(ActiveRecord::Deadlocked, attempts: 3).

3. Final Answer:

   retry_on(ActiveRecord::Deadlocked, attempts: 3) -> Option A

4. Quick Check:

   Correct method call syntax = retry_on(ActiveRecord::Deadlocked, attempts: 3) [OK]

Hint: Use parentheses with keyword args for retry_on [OK]

Common Mistakes:

• Omitting parentheses with keyword arguments
• Using equal sign instead of colon for options
• Missing commas between arguments

3. Given this job code:

class MyJob < ApplicationJob
  retry_on StandardError, attempts: 2

  def perform
    raise StandardError, "fail"
  end
end

MyJob.perform_now

What happens when MyJob.perform_now is called?

medium

A. The job silently discards the error and finishes.

B. The job raises StandardError once and stops.

C. The job retries twice after failures, then raises error.

D. The job retries once after the first failure, then raises error.

Solution

1. Step 1: Understand retry_on with attempts: 2

   It means the job will try up to 2 times total (1 initial + 1 retry) before giving up.

2. Step 2: Analyze job behavior

   The job raises StandardError every time. It runs once, fails, retries once, then fails again and raises error.

3. Final Answer:

   The job retries once after the first failure, then raises error. -> Option D

4. Quick Check:

   attempts: 2 means 1 retry [OK]

Hint: attempts count includes first try, so retries = attempts - 1 [OK]

Common Mistakes:

• Thinking attempts means retries count
• Assuming job discards error automatically
• Believing job retries infinitely

4. Identify the error in this job code snippet:

class ExampleJob < ApplicationJob
  retry_on(StandardError, attempts: 3)

  def perform
    # job logic
  end
end

medium

A. The retry_on method should be called inside perform method.

B. The retry_on method should not have parentheses.

C. The retry_on method is correctly used; no error.

D. The retry_on method should be declared with a block.

Solution

1. Step 1: Check retry_on usage location

   retry_on is a class-level method and should be declared outside perform method, as shown.

2. Step 2: Verify syntax correctness

   Using parentheses with arguments is valid Ruby syntax here.

3. Final Answer:

   The retry_on method is correctly used; no error. -> Option C

4. Quick Check:

   retry_on class method syntax is correct [OK]

Hint: retry_on is a class method, not inside perform [OK]

Common Mistakes:

• Placing retry_on inside perform method
• Thinking parentheses are disallowed
• Expecting retry_on to require a block

5. You want a job to retry up to 5 times on Net::OpenTimeout errors but discard immediately on ArgumentError. Which code correctly implements this behavior?

hard

A. class NetworkJob < ApplicationJob
discard_on Net::OpenTimeout
retry_on ArgumentError, attempts: 5

def perform
# network call
end
end

B. class NetworkJob < ApplicationJob
retry_on Net::OpenTimeout, attempts: 5
discard_on ArgumentError

def perform
# network call
end
end

C. class NetworkJob < ApplicationJob
retry_on Net::OpenTimeout
retry_on ArgumentError, attempts: 5

def perform
# network call
end
end

D. class NetworkJob < ApplicationJob
discard_on Net::OpenTimeout, attempts: 5
discard_on ArgumentError

def perform
# network call
end
end

Solution

1. Step 1: Understand retry_on and discard_on roles

   retry_on retries job on specified error; discard_on stops retries and discards job immediately.

2. Step 2: Match errors to correct methods

   Net::OpenTimeout should retry up to 5 times, so use retry_on with attempts: 5. ArgumentError should discard immediately, so use discard_on.

3. Final Answer:

   Code with retry_on Net::OpenTimeout, attempts: 5 and discard_on ArgumentError -> Option B

4. Quick Check:

   retry_on for retry, discard_on for discard [OK]

Hint: retry_on = retry; discard_on = stop and discard [OK]

Common Mistakes:

• Swapping retry_on and discard_on for errors
• Missing attempts option for retry_on
• Using discard_on with attempts option