Retry and rerun runs

Use manual retry for a failed run after its cause has been fixed. Use rerun when you intentionally want a new execution of any terminal run.

import { asId, queue, type RunId, type RunlaneRuntime } from '@runlane/core'

const recoveryQueue = queue({ name: 'recovery' })

export async function retryFailedRun(runlane: RunlaneRuntime, failedRunId: RunId) {
  return runlane.runs.retry(failedRunId)
}

export async function rerunTerminalRun(runlane: RunlaneRuntime, sourceRunId: RunId) {
  return runlane.runs.rerun(sourceRunId)
}

export async function rerunInRecoveryQueue(runlane: RunlaneRuntime, sourceRunId: RunId) {
  return runlane.runs.rerun(sourceRunId, {
    queue: recoveryQueue,
    runId: asId<'run'>('run.recovery.2026-01-15'),
  })
}

Retry a failed run

The source must be failed. Runlane creates a queued child with the source task and payload and records a manual-retry source link. The failed source remains unchanged for audit history.

Rerun terminal work

The source must be terminal. Rerun also creates a queued child and leaves the original untouched.

Both methods accept an optional queue override, operator actor metadata, and an explicit branded child run id. rerunInRecoveryQueue() shows the queue and run-id overrides.

The source task must still be registered so Runlane can resolve its handler, queue, concurrency, and singleton policies. The child reuses the source run's saved validated payload without applying the input schema again.

Linked runs do not apply the task's idempotency key. Otherwise, the old owner could be returned instead of creating the operator-requested run. Singleton and concurrency policies still apply.

To verify the action, confirm the returned child is queued, its source.sourceRunId names the original, and the original record is unchanged. Then let the normal worker or delivery path execute the child.

retry() rejects a non-failed source. rerun() rejects an active source. TaskNotFound means the operator runtime does not have the source task registered. Fix the runtime catalog rather than copying the payload into an unrelated trigger.

Use automatic retries for transient failures handled by policy rather than an operator.