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.

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.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• runId required to start run
• Path and content are required
• Path is required
• runId required to cancel workflow run
• runId required to stream workflow

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

Appendix: 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)