mastra-ai/mastra · error · HTTPException

runId required to cancel workflow run

Error message

runId required to cancel workflow run

What it means

This 400 error is thrown by the cancel-workflow-run handler when the request provides a workflowId but omits `runId`. Canceling a run requires knowing which specific run execution to cancel; without runId the handler cannot proceed and rejects with 400.

Source

Thrown at packages/server/src/server/handlers/workflows.ts:1308

  method: 'POST',
  path: '/workflows/:workflowId/runs/:runId/cancel',
  responseType: 'json',
  pathParamSchema: workflowRunPathParams,
  responseSchema: workflowControlResponseSchema,
  summary: 'Cancel workflow run',
  description: 'Cancels an in-progress workflow execution',
  tags: ['Workflows'],
  requiresAuth: true,
  handler: async ({ mastra, workflowId, runId, requestContext }) => {
    try {
      const effectiveResourceId = getEffectiveResourceId(requestContext, undefined);

      if (!workflowId) {
        throw new HTTPException(400, { message: 'Workflow ID is required' });
      }

      if (!runId) {
        throw new HTTPException(400, { message: 'runId required to cancel workflow run' });
      }

      const { workflow } = await listWorkflowsFromSystem({ mastra, workflowId });

      if (!workflow) {
        throw new HTTPException(404, { message: 'Workflow not found' });
      }

      const run = await workflow.getWorkflowRunById(runId);

      if (!run) {
        throw new HTTPException(404, { message: 'Workflow run not found' });
      }

      await validateRunOwnership(run, effectiveResourceId);

      const _run = await workflow.createRun({ runId, resourceId: run.resourceId });

View on GitHub (pinned to 75dd419e61)

Solutions

1. Include the runId of the run to cancel in the request (path parameter per the route definition).
2. Capture the runId from the workflow start/startAsync response and store it for later cancellation.
3. If no runId exists, the run may have already finished — list runs to confirm a cancellable (running) run first.
4. Verify the correct cancel endpoint/route is being used for the installed @mastra/core version.

Example fix

// before
await client.getWorkflow('orderProcessing').cancelRun();
// after
await client.getWorkflow('orderProcessing').cancelRun(runId);

if (!runId) throw new Error('cancelRun requires the runId returned when the run was started');

function hasRunId(p: { runId?: string }): p is { runId: string } {
  return typeof p.runId === 'string' && p.runId.length > 0;
}

try {
  await client.getWorkflow(workflowId).cancelRun(runId);
} catch (e) {
  if (e?.status === 400 && /runId required to cancel/.test(e?.message ?? '')) {
    throw new Error('Capture runId from the start() response and pass it to cancelRun');
  }
  throw e;
}

When it happens

Trigger: Calling the cancel workflow run endpoint without the runId path/body parameter, e.g. POST /api/workflows/:workflowId/cancel with no run identifier.

Common situations: Frontend cancel button wired before the run has been started (runId not yet captured from the start response); confusing the workflowId with the runId; older API shape where runId was embedded differently.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• runId required to time travel workflow stream
• Step is required and must be a valid step or array of steps
• runId required to stream workflow
• runId required to resume workflow
• runId required to start run

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/871b5aee0f2d5d2a. Report an issue: GitHub.