Skip to main content

CANCEL A STUCK RUN

This guide shows you how to stop a workflow or model method run that is stuck, no longer needed, or was started by mistake.

Prerequisites

  • Swamp installed and on your PATH
  • An initialised repo (swamp repo init)
  • A workflow or model method run currently in progress

1. Identify the stuck run

If you started the run interactively and the terminal is still open, skip to step 2 — you can cancel directly from the terminal.

If the run is executing in the background or on a swamp serve instance, find it with the run tracker:

swamp run history --active

Alternatively, list by type. For workflows:

swamp workflow list

For model method runs:

swamp model list

2. Cancel the run

For a workflow:

swamp workflow cancel my-workflow

For a model method run:

swamp model cancel my-server

If you started the run interactively with swamp workflow run or swamp model method run and the terminal is still open, press Ctrl+C instead. The CLI intercepts the signal and cancels the run cleanly.

To record why you cancelled (useful for audit trails):

swamp workflow cancel my-workflow --reason 'Deploying a hotfix instead'

2a. Cancel a serve-owned run

swamp workflow cancel --all only cancels locally-owned runs — runs owned by a swamp serve instance are skipped. To cancel a serve-owned run, target the server with --server and specify the run ID with --run:

swamp workflow cancel my-workflow --server wss://swamp.example.com --run 3f8a2b1c

2b. Recover a run after a force exit

Pressing Ctrl+C twice, or killing the process, force-exits swamp workflow run before it can record the run's end. The run stays running with no process behind it, and swamp workflow resume refuses it:

Error: No suspended runs found for workflow "slow". The latest run (faebb8ba-cb7b-43a2-90d7-d39b1dfd2db5) is recorded as running, but its owning process is gone. Recover it with 'swamp workflow recover slow --run faebb8ba-cb7b-43a2-90d7-d39b1dfd2db5', then resume it.

To keep the run's completed steps and run the rest, recover it, then resume it:

swamp workflow recover slow --run faebb8ba-cb7b-43a2-90d7-d39b1dfd2db5
swamp workflow resume slow --run faebb8ba-cb7b-43a2-90d7-d39b1dfd2db5

If a step was mid-flight at the force exit and has no guard expression, recover asks you to accept that it runs again. Add --acknowledge-unknown:

swamp workflow recover slow --run faebb8ba-cb7b-43a2-90d7-d39b1dfd2db5 --acknowledge-unknown
Recovered run faebb8ba-cb7b-43a2-90d7-d39b1dfd2db5 — unknown steps reset to pending.
Resume with: swamp workflow resume slow --run faebb8ba-cb7b-43a2-90d7-d39b1dfd2db5

To settle every run on this host left behind by a dead process at once, run swamp run doctor --fix. Each run it settles is interrupted; recover and resume it as above to run its remaining steps.

To abandon the run instead, cancel it with swamp workflow cancel slow --run <id>. A cancelled run cannot be resumed.

3. Verify the cancellation

The run's status transitions to cancelled. Steps that were running at the time of cancellation also show cancelled; steps that had already completed keep their original status.

Next steps

← PreviousGate a Workflow with Manual ApprovalNext →Reuse a Model with the Factory Pattern