mastra-ai/mastra · error · HTTPException

Workflow ID is required

Error message

Workflow ID is required

What it means

listWorkflowsFromSystem resolves a workflow either from the temporary-workflow registry or from the Mastra instance's storage, and it refuses to run without a `workflowId`. The 400 'Workflow ID is required' is thrown before any lookup when workflowId is falsy. It is an internal helper shared by several workflow route handlers, so the error surfaces through whichever endpoint omitted the ID.

Source

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

      reader.releaseLock();
      activeRunStreamCachers.delete(runId);
    }
  })();

  return toClient;
}

export interface WorkflowContext extends Context {
  workflowId?: string;
  runId?: string;
  requestContext?: RequestContext;
}

async function listWorkflowsFromSystem({ mastra, workflowId }: WorkflowContext) {
  const logger = mastra.getLogger();

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

  let workflow;

  // First check registry for temporary workflows
  workflow = WorkflowRegistry.getWorkflow(workflowId);

  if (!workflow) {
    try {
      workflow = mastra.getWorkflowById(workflowId);
    } catch (error) {
      logger.debug('Error getting workflow, searching agents for workflow', error);
    }
  }

  if (!workflow) {
    logger.debug('Workflow not found, searching agents for workflow', { workflowId });
    const agents = mastra.listAgents();

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass the workflowId in the request path or call arguments
2. Verify the workflow id matches the id used at new Workflow()/register time
3. If listing all workflows, use the workflows list endpoint that does not require a single id

Example fix

// before
const { workflow } = await listWorkflowsFromSystem({ mastra, workflowId: undefined });
// after
const { workflow } = await listWorkflowsFromSystem({ mastra, workflowId: 'myWorkflowId' });

async function safeGetWorkflow(mastra, workflowId) {
  if (!workflowId) throw new TypeError('workflowId is required');
  return listWorkflowsFromSystem({ mastra, workflowId });
}

function hasWorkflowId(args): args is WorkflowContext & { workflowId: string } {
  return typeof (args as any)?.workflowId === 'string' && (args as any).workflowId.length > 0;
}

try {
  const { workflow } = await listWorkflowsFromSystem({ mastra, workflowId });
} catch (e) {
  if (e instanceof HTTPException && e.status === 400) {
    return { error: 'workflowId is required' };
  }
  throw e;
}

When it happens

Trigger: Calling any workflow route that resolves to listWorkflowsFromSystem (e.g. GET workflow details/runs) without the workflowId path parameter; a client passing undefined workflowId to listWorkflows on aMastra instance.

Common situations: Manually constructed URLs missing the workflow id segment; programmatic use of a Mastra instance where the workflow id variable is undefined because the workflow was never registered under the expected name.

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

• Run ID is required
• perPage must be a positive integer
• page must be a non-negative integer
• runId required to restart workflow
• resourceId and threadId are required when runId is not provi

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