How to cancel running workflows

You can cancel a scheduled or in-progress flow run from the CLI, UI, REST API, or Python client.

{/*

*/}

When requesting cancellation, the flow run moves to a "Cancelling" state. If the deployment is associated with a work pool, then the worker monitors the state of flow runs and detects that cancellation is requested. The worker then sends a signal to the flow run infrastructure, requesting termination of the run. If the run does not terminate after a grace period (default of 30 seconds), the infrastructure is killed, ensuring the flow run exits.

{/*

*/}

Flow run cancellation requires that the flow run is associated with a deployment. A monitoring process must be running to enforce the cancellation.

Inline nested flow runs (those created without run_deployment), cannot be cancelled without cancelling the parent flow run. To cancel a nested flow run independent of its parent flow run, we recommend deploying it separately and starting it using the run_deployment function. </Warning>

Cancellation is resilient to restarts of Prefect workers. To enable this, we attach metadata about the created infrastructure to the flow run. Internally, this is referred to as the infrastructure_pid or infrastructure identifier. Generally, this is composed of two parts:

• Scope: identifying where the infrastructure is running.
• ID: a unique identifier for the infrastructure within the scope.

{/*

*/}

The scope ensures that Prefect does not kill the wrong infrastructure. For example, workers running on multiple machines may have overlapping process IDs but should not have a matching scope.

{/*

*/}

The identifiers for infrastructure types are:

• Processes: The machine hostname and the PID.
• Docker Containers: The Docker API URL and container ID.
• Kubernetes Jobs: The Kubernetes cluster name and the job name.

While the cancellation process is robust, there are a few issues than can occur:

• If the infrastructure for the flow run does not support cancellation, cancellation will not work.
• If the identifier scope does not match when attempting to cancel a flow run, the worker cannot cancel the flow run. Another worker may attempt cancellation.
• If the infrastructure associated with the run cannot be found or has already been killed, the worker marks the flow run as cancelled.
• If the infrastructre_pid is missing, the flow run is marked as cancelled but cancellation cannot be enforced.
• If the worker runs into an unexpected error during cancellation, the flow run may or may not be cancelled depending on where the error occurred. The worker will try again to cancel the flow run. Another worker may attempt cancellation.

Cancel through the CLI

From the command line in your execution environment, you can cancel a flow run by using the prefect flow-run cancel CLI command, passing the ID of the flow run.

prefect flow-run cancel 'a55a4804-9e3c-4042-8b59-b3b6b7618736'

Cancel through the UI

Navigate to the flow run's detail page and click Cancel in the upper right corner.

Cancel through the Python client

To request cancellation programmatically, set the flow run state to CANCELLING. This is the same state used by the CLI, UI, and automation cancellation actions.

from uuid import UUID

from prefect import get_client
from prefect.client.schemas.objects import State, StateType


flow_run_id = UUID("a55a4804-9e3c-4042-8b59-b3b6b7618736")

with get_client(sync_client=True) as client:
    result = client.set_flow_run_state(
        flow_run_id=flow_run_id,
        state=State(type=StateType.CANCELLING, name="Cancelling"),
    )

print(result.status)

Cancel through the REST API

To request cancellation with the REST API, set the flow run state to CANCELLING.

curl -X POST "$PREFECT_API_URL/flow_runs/a55a4804-9e3c-4042-8b59-b3b6b7618736/set_state" \
  -H "Content-Type: application/json" \
  -d '{"state": {"type": "CANCELLING", "name": "Cancelling"}}'