mastra-ai/mastra · error · HTTPException

runId required to resume workflow

Error message

runId required to resume workflow

What it means

Thrown by the resume handler when `runId` is missing after the workflowId check passes. Resuming a suspended workflow requires the specific run to resume, so the server rejects with HTTP 400 before touching storage.

Source

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

  responseType: 'stream',
  pathParamSchema: workflowIdPathParams,
  queryParamSchema: runIdSchema,
  bodySchema: resumeBodySchema,
  responseSchema: streamResponseSchema,
  summary: 'Resume workflow stream',
  description: 'Resumes a suspended workflow execution and continues streaming results',
  tags: ['Workflows'],
  requiresAuth: true,
  handler: async ({ mastra, workflowId, runId, requestContext, ...params }) => {
    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 resume workflow' });
      }

      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 });
      const serverCache = mastra.getServerCache();

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass the runId of the suspended run to the resume call.
2. Persist the runId returned from `workflow.createRun()`/`start()` so it is available at resume time.
3. Look up existing runs for the workflow (runs list API) if the runId was lost.

Example fix

// before
await workflow.resume({ resumeData }) // runId missing
// after
await workflow.resume({ runId, step: 'approval', resumeData })

if (!runId || typeof runId !== 'string') {
  throw new TypeError('runId is required to resume a suspended workflow run');
}
await client.resumeWorkflow(workflowId, runId, { resumeData });

function isRunId(x: unknown): x is string {
  return typeof x === 'string' && x.trim().length > 0;
}

try {
  await workflow.resume({ runId, resumeData });
} catch (e) {
  if (e instanceof MastraClientError && e.status === 400 && /runId/.test(e.message)) {
    console.error('Resume call missing runId; did you persist it at createRun time?');
  }
  throw e;
}

When it happens

Trigger: POST to the resume endpoint without a runId in path/body; calling the SDK resume method without the run identifier; runId variable undefined because the suspended-run handle was lost (e.g. not persisted by the caller).

Common situations: After a server restart the caller no longer knows the runId and sends an empty value; passing the workflow id in place of the run id by mistake; forgetting to persist runId when initiating the workflow.

Related errors

• runId required to start run
• runId required to stream workflow
• runId required to time travel workflow stream
• runId required to cancel workflow run
• Path is required

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