mastra-ai/mastra · error · HTTPException

runId required to restart workflow

Error message

runId required to restart workflow

What it means

The POST /api/workflows/:workflowId/restart-run (async) handler requires a runId path/query parameter identifying which workflow run to restart. The server validates required parameters before doing any storage lookup and throws HTTPException(400) when runId is missing. This is a client-side request-shape error, not a server fault.

Source

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

  responseType: 'json',
  pathParamSchema: workflowIdPathParams,
  queryParamSchema: runIdSchema,
  bodySchema: restartBodySchema,
  responseSchema: workflowExecutionResultSchema,
  summary: 'Restart workflow asynchronously',
  description: 'Restarts an active workflow execution asynchronously',
  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 restart 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 result = await _run.restart({ ...params, requestContext });

View on GitHub (pinned to 75dd419e61)

Solutions

1. Include the runId parameter in the request path/query, e.g. POST /api/workflows/:workflowId/restart-run/:runId.
2. Fetch the run id first via the workflow runs list endpoint if you don't have it.
3. Coerce/trim the value: an empty string runId will also fail this check, so ensure the client sends a non-empty id.

Example fix

// before
await fetch(`/api/workflows/${workflowId}/restart-run`);
// after
await fetch(`/api/workflows/${workflowId}/restart-run/${runId}`);

if (!runId || typeof runId !== 'string' || runId.trim() === '') {
  throw new Error('runId is required before calling restart-run');
}

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

try {
  await restartRun(workflowId, runId);
} catch (e) {
  if (isHttpError(e, 400) && /runId required/.test(e.message)) {
    throw new Error('Client bug: runId must be supplied to restart a workflow run');
  }
  throw e;
}

When it happens

Trigger: Calling the restart-run async endpoint without supplying runId in the request (missing path param or query string), e.g. POST /workflows/myWorkflow/restart-run with only workflowId present.

Common situations: Client SDK or fetch call built from a template where the runId variable was undefined/null; UI code that lists workflows but forgot to pass the selected run's id; copying a restart-all route pattern for the per-run route.

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

• Workflow ID is required
• Run ID is required
• runId required to time travel workflow stream
• runId required to cancel workflow run
• Step is required and must be a valid step or array of steps

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