Retries, waits, and recovery
Choose the right way to continue work after it stops.
Several paths can lead to another task attempt. They are not interchangeable because each one records a different reason.
| Path | Use it when | What Runlane records |
|---|---|---|
| Retry | The task failed and trying again may work | Failure, attempt count, and next due time |
| Release | The task is waiting for an expected condition | A successful pause without failure or retry cost |
| Signal | Something should wake current matching waiters | A one-time wakeup, not a stored result |
| Token | An external result must remain readable | A durable pending, completed, or timed_out decision |
| Recovery | Delivery or ownership stopped making progress | Framework repair of the existing run |
Retry failures
A retry follows a task failure. The task policy decides whether another attempt is allowed and when it is due. Earlier failures stay in history even if a later attempt succeeds.
Use retry failed work for temporary failures.
Release expected waits
A release ends the current attempt without recording a task failure. The task can wait until a time, for a signal, for a durable token, or for another run.
The next attempt starts the handler from the beginning. Use durable steps or idempotency when earlier side effects must not run again. Follow wait without failing for the available wait types.
Use signals and tokens for different jobs
A signal wakes runs that are already waiting on the same key. It does not retain a value for a future waiter.
A token stores one terminal result and can resume every retained run link in bounded batches. Use it for approvals and other decisions that must remain inspectable. See human-in-the-loop flows.
Let recovery repair the same run
Recovery handles framework state such as expired worker leases, deferred outbox publishing, abandoned cancellation, and fixed attempt deadlines. It preserves a lifecycle change that won the race before recovery.
When both a lease and a fixed attempt deadline have expired, timeout finalization wins. Reacquiring the run first would clear the deadline and lose the durable timeout result.
Maintenance connects due work back to delivery. Polling workers can find due work in storage. Transport deployments need maintenance to create and publish a fresh wakeup. Completing a token or reaching a due time does not itself send an SQS message.
If work stays stuck, use observe and recover runs. More retries will not fix missing maintenance, and a replacement trigger will lose the original run's audit link.