Job Lifecycle

Oban jobs follow a state machine that governs their lifecycle. Each job transitions through distinct states from the moment it's inserted until it reaches completion or another terminal state.

Job States

Jobs exist in one of eight possible states:

• suspended — Jobs that are held and won't be processed until they are resumed
• available — Jobs ready to be executed
• scheduled — Jobs waiting for a specific time to become available for execution
• executing — Jobs currently running
• retryable — Jobs that failed but will be automatically retried
• completed — Jobs that finished successfully
• cancelled — Jobs that were purposefully stopped
• discarded — Jobs that exhausted all attempts and won't be retried again

Initial States

When you first insert a job into Oban, it enters one of two initial states:

• available - The default state for new jobs that should be executed immediately
• scheduled - When you provide a scheduled_at timestamp or schedule_in delay

# Job inserted as "available"
%{id: 123} |> MyApp.Worker.new() |> Oban.insert()

# Job inserted as "scheduled"
%{id: 123} |> MyApp.Worker.new(schedule_in: 60) |> Oban.insert()

Executing State

When a job becomes available, it waits for a queue with available capacity to claim it.

• available → executing - The job is claimed by a queue with available capacity and execution begins
• scheduled → available → executing - When the scheduled time arrives, the job becomes available and a queue may claim it

Retry Cycle

When a job fails but hasn't reached its max_attempts limit, it automatically schedules a retry. The retry cycle follows these steps:

• executing → retryable - The job is scheduled to run after a backoff period
• retryable → available → executing - The backoff period elapsed and the job can be picked up for another attempt

This cycle continues until it reaches a final state.

Final States

After execution, a job will transition to one of these final states:

• executing → completed - The job executed successfully
• executing → cancelled - The job returned {:cancel, reason} or was manually cancelled
• executing → discarded - The job failed and reached its maximum retry attempts

Cleaning Up Jobs {: .tip}

Oban's Pruner only removes final state jobs (completed, cancelled, and discarded). This prevents your database from growing indefinitely while still providing visibility into recently finished jobs.

Understanding the job lifecycle helps you build more resilient systems by properly handling failure cases, monitoring job progress, and designing appropriate retry strategies for your specific workloads.