> For the complete documentation index, see [llms.txt](https://docs.pyck.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pyck.cloud/graphql-api/mutations/cancelworkflow.md).

# Cancel Workflow

cancelWorkflow Mutation

Audience: Programmer

Requests graceful cancellation of a running Temporal workflow execution.

The mutation delegates to Temporal's native cancellation mechanism. Unlike termination, cancellation is cooperative: the target workflow receives a cancellation signal (via `ctx.Done()`) and can run cleanup logic using `workflow.NewDisconnectedContext` before finally exiting. This makes cancellation the preferred way to stop long-running workflows while still releasing resources, emitting compensating events, or persisting final state.

The mutation returns once Temporal has accepted the cancel request. It does **not** wait for the workflow to actually reach a terminal state. Use the `checkWorkflowStatus` mutation or the `workflowExecutions` query to observe the eventual status transition to `CANCELED`.

## Arguments

| Name    | Type                   | Description                                 |
| ------- | ---------------------- | ------------------------------------------- |
| `input` | `CancelWorkflowInput!` | Identifies the workflow execution to cancel |

## Return Type

`CancelWorkflowPayload!` - Echoes the identifiers of the workflow execution whose cancellation was requested.

## Input Fields

`CancelWorkflowInput`:

| Field           | Type      | Description                                                                 |
| --------------- | --------- | --------------------------------------------------------------------------- |
| `workflowID`    | `String!` | The workflow ID (business-meaningful identifier) of the execution to cancel |
| `workflowRunID` | `String!` | The Temporal-generated run ID of the specific execution to cancel           |

## Return Fields

`CancelWorkflowPayload`:

| Field           | Type      | Description                                      |
| --------------- | --------- | ------------------------------------------------ |
| `workflowID`    | `String!` | The workflow ID whose cancellation was requested |
| `workflowRunID` | `String!` | The run ID whose cancellation was requested      |

## Usage Example

```graphql
mutation {
  cancelWorkflow(
    input: {
      workflowID: "picking-order-workflow-42",
      workflowRunID: "abc123de-f456-7890-ghij-klmnopqrstuv"
    }
  ) {
    workflowID
    workflowRunID
  }
}
```

## JavaScript Example

```javascript
const CANCEL_WORKFLOW = gql`
  mutation CancelWorkflow($input: CancelWorkflowInput!) {
    cancelWorkflow(input: $input) {
      workflowID
      workflowRunID
    }
  }
`;

const { data } = await client.mutate({
  mutation: CANCEL_WORKFLOW,
  variables: {
    input: {
      workflowID: "picking-order-workflow-42",
      workflowRunID: "abc123de-f456-7890-ghij-klmnopqrstuv"
    }
  }
});

console.log(
  `Cancellation requested for workflow ${data.cancelWorkflow.workflowID} (run ${data.cancelWorkflow.workflowRunID})`
);
```

## Behavior

* The resolver resolves the Temporal client for the caller's tenant via the workflow router; an invalid or unavailable client yields an `ErrInvalidWorkflowClient` error.
* On success, Temporal enqueues a `WorkflowExecutionCancelRequested` event on the target workflow history.
* The workflow code observes cancellation through `ctx.Err() == workflow.ErrCanceled` (or the `ctx.Done()` channel) and may run cleanup activities with a disconnected context before returning.
* The final workflow status will typically transition to `CANCELED`, though a workflow that ignores cancellation may still complete, fail, or time out.

## Error Handling

Possible errors include:

* **Invalid workflow client**: The tenant does not have a reachable Temporal client configured.
* **Workflow not found**: No execution exists for the provided `workflowID` / `workflowRunID` pair.
* **Workflow already closed**: The target execution is already in a terminal state (completed, failed, canceled, terminated, timed out).
* **Permission denied**: The caller is not authorized to cancel workflows in the target tenant.

## Important Notes

* Cancellation is cooperative and asynchronous. The mutation returns once the request is accepted, not when the workflow has finished reacting to it.
* Workflows that want to perform cleanup on cancel must use `workflow.NewDisconnectedContext` for the cleanup activities; otherwise those activities inherit the already-canceled context and exit immediately.
* To forcibly stop a workflow without giving it a chance to clean up, a termination API (not exposed here) would be required. Prefer cancellation whenever possible.
* Both `workflowID` and `workflowRunID` are required; the run ID ensures that a specific execution is targeted rather than the latest run of a given workflow ID.
* To confirm the cancellation took effect, poll `checkWorkflowStatus` or `workflowExecutions` until the status reaches `CANCELED`.

## Related

* Input: [CancelWorkflowInput](/graphql-api/inputs/cancelworkflowinput.md)
* Mutation: [checkWorkflowStatus](/graphql-api/mutations/checkworkflowstatus.md)
* Query: [workflowExecutions](/graphql-api/queries/workflowexecutions.md)

## Service

This mutation is defined in the **workflow** service.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.pyck.cloud/graphql-api/mutations/cancelworkflow.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.