When a pipeline job reaches status: "error", you have two options for how to re-run it. The retryMode parameter on runPipeline controls which one you get. Choosing correctly means the difference between re-running only the failed work versus discarding everything and starting over.
RetryMode type
Mode behaviors
When to use resume
"resume" is the right default for almost every retry scenario. Because both { kind: "error" } returns and thrown exceptions preserve the checkpoint, "resume" works correctly regardless of how the failure happened. Only the phase that was running at the time of the error re-executes — all earlier phases are skipped.
Use "resume" when:
- A transient external dependency failed (API timeout, network blip)
- The phase threw an unexpected exception and you’ve deployed a fix
- A
{ kind: "error" } result was returned and you want to retry the same operation
- Mid-phase
saveState was called — resume picks up from the exact saved position
Expose this as a “Retry” button in your UI. Users understand “retry” to mean “try again from where it failed.”
When to use full
"full" is the nuclear option. It discards all checkpoint state and forces a fresh run through every phase from the beginning. This is appropriate when:
- The saved state itself has become corrupt or structurally invalid
- You’ve changed
initialState in a way that’s incompatible with the stored checkpoint
- The user explicitly wants to restart (e.g. they’ve edited the input document and want a clean run)
- You’ve refactored phase logic in a way that makes resuming from an old checkpoint unsafe
Label this button clearly — “Start over” or “Reset and retry” — not just “Retry”. Users who click it will lose all progress from previous phases.
Retry example
Both modes use the same runPipeline call — only the retryMode value differs:
runPipeline only writes to storage and enqueues a scheduler event — it’s safe to call from a UI action or mutation handler without worrying about execution timeouts.
What happens when retryMode is omitted
If you call runPipeline without a retryMode and a checkpoint already exists, the library behaves as "resume". If no checkpoint exists (fresh job or already-completed job), both modes produce the same result — a fresh run from initialPhase.
You can always pass retryMode: "resume" explicitly on new jobs without any side effects. Making the intent explicit is cleaner than relying on the default, especially in code that may also handle re-runs.
Combining with the UI components
The RetryButtons UI component handles both modes in one component. Pass an onRetry handler that calls retryJob with the mode it receives:
RetryButtons renders a “Retry” button that calls onRetry("resume") and a “Restart” button that calls onRetry("full"). See UI Components for customization options. 
