Error: 'Workflow must be in a terminal state to be rerun' When Using the Rerun API

Overview

When using the CircleCI API v2 to rerun a workflow, you may receive the following error:

Workflow must be in a terminal state to be rerun

This error indicates that you are attempting to rerun a workflow that is still in progress. This is expected behavior and aligns with how the CircleCI web app has always worked.

Why this happens

CircleCI does not allow rerunning a workflow that is already in progress. This restriction exists because:

Rerunning an active workflow could cause data inconsistencies between the original and rerun workflows
It could lead to duplicate job executions and unexpected state conflicts
The system was not designed to handle concurrent executions of the same workflow

The CircleCI web app has always enforced this restriction. If you have ever tried to click the "Rerun" button on an active workflow in the UI, you would have seen the options greyed out with the message "Cannot rerun the current workflow until it has finished."

When this behavior was enforced in the API

Prior to April 28, 2026, the API allowed rerunning workflows that were still running, even though the UI did not. This inconsistency has now been resolved. The API now enforces the same restriction as the UI to ensure consistent behavior across all interfaces.

If you have automation scripts that previously relied on calling the rerun API on active workflows, those scripts will now receive this error.

What is a terminal state?

A workflow is in a terminal state when it has finished execution and cannot change status further. The following table shows all workflow states and whether they are terminal:

Status	Description	Terminal
`success`	All jobs completed successfully	Yes
`failed`	One or more jobs failed	Yes
`canceled`	The workflow was canceled	Yes
`error`	An internal error occurred starting a job	Yes
`unauthorized`	A job could not access a required restricted context	Yes
`running`	The workflow is currently executing	No
`on_hold`	The workflow is waiting for approval	No
`failing`	A job failed but other jobs are still running	No
`queued`	The workflow is queued (serial group)	No

You can only rerun workflows that are in a terminal state (the "Yes" rows above).

How to resolve this error

Option 1: Wait for the workflow to complete

Allow the workflow to finish naturally. Once it reaches a terminal state (success, failed, canceled, etc.), you can rerun it.

Option 2: Cancel the workflow first, then rerun

If you need to rerun immediately, cancel the running workflow first:

curl --request POST \
  --url "https://circleci.com/api/v2/workflow/${WORKFLOW_ID}/cancel" \
  --header "Circle-Token: ${CIRCLE_TOKEN}"

Wait for the workflow to reach the canceled state, then rerun:

curl --request POST \
  --url "https://circleci.com/api/v2/workflow/${WORKFLOW_ID}/rerun" \
  --header "Circle-Token: ${CIRCLE_TOKEN}" \
  --header "Content-Type: application/json"

Option 3: Update your automation to check workflow status

Before attempting a rerun, check the workflow status:

curl --request GET \
  --url "https://circleci.com/api/v2/workflow/${WORKFLOW_ID}" \
  --header "Circle-Token: ${CIRCLE_TOKEN}"

The response includes a status field. Only proceed with the rerun if the status is a terminal state.

Other rerun limitations

In addition to the terminal state requirement, be aware of these other rerun limitations:

90-day limit: Workflows cannot be rerun if they were triggered more than 90 days ago. See Cannot Rerun an Old Workflow or On Hold Job.
100 rerun limit: Individual workflows have a hard limit of 100 reruns (including reruns of reruns).

Additional resources