SextantDocs
v2.4latest
v2.4latestv1.9legacy

Switching keeps you on the same page when it exists in the other version.

On this page

Job lifecycle

The seven states a job can be in, what moves it between them, and which transitions you can trigger yourself.

Updated Getting started Version v2.4

Every job is in exactly one state. The server owns the transitions; your handler only decides whether an attempt succeeded.

Job lifecycle A job starts scheduled, becomes queued, then running. A running job either succeeds or fails. A failed job is retried with backoff until max attempts, then becomes dead. Scheduled and queued jobs can be cancelled. scheduledwaiting for run_at queuedready, no worker yet runningleased by a worker succeededhandler returned failederror or timeout deadattempts exhausted cancelled retry after backoff (attempt < max_attempts) attempt = max_attempts
Dashed lines are optional paths: a retry after a failure, and cancellation before a job starts.

States

State Meaning Leaves the state when
scheduled Waiting for run_at, or for a retry backoff to elapse The time arrives
queued Runnable, no worker has taken it A worker leases it
running Leased by a worker The handler returns, throws, times out, or the lease expires
succeeded The last attempt returned without error Never (terminal)
failed The last attempt failed and more attempts remain The backoff elapses, then it becomes scheduled and queued again
dead Attempts exhausted Someone retries it
cancelled Cancelled before it started, or after a cancellation signal Never (terminal)

What counts as a failed attempt

An attempt fails when:

  • the handler throws, rejects or returns a non-zero exit code;
  • it runs longer than the queue’s timeout;
  • the worker stops renewing the lease (crash, network partition, SIGKILL).

The last case counts as an attempt even though no error was reported, which is why a crash-looping handler ends up dead instead of retrying forever.

Transitions you can trigger

cancelscheduled, queued, running
sextant jobs cancel <id> or POST /v2/jobs/{job_id}/cancel. A running handler gets a cancellation signal and a grace period (cancel_grace, 10 seconds by default).
retryfailed, dead
sextant jobs retry <id> or POST /v2/jobs/{job_id}/retry. The attempt counter resets to zero.

You cannot edit the payload of an existing job. Cancel it and create a new one with the corrected payload and a fresh idempotency key.

Retention decides how long finished jobs stay visible. See retention.