What causes "Workflow ${workflowId} not found" in mastra-ai/mastra?

Verify the workflowId string matches exactly the key used at registration.

Workflow ${workflowId} not found

Error message

Workflow ${workflowId} not found

What it means

handleWorkflowStream looks up the workflow by ID via mastra.getWorkflowById(workflowId) before creating a run. When no workflow is registered under that ID, this error is thrown — the server has no workflow bound to the requested identifier.

Source

Thrown at client-sdks/ai-sdk/src/workflow-route.ts:116

  includeTextStreamParts = true,
  sendReasoning = false,
  sendSources = false,
}: WorkflowStreamHandlerOptions): Promise<SupportedUIMessageStream> {
  const {
    runId,
    resourceId: resourceIdFromParams,
    inputData,
    initialState,
    resumeData,
    requestContext,
    ...rest
  } = params;
  const resourceIdFromContext = requestContext?.get(MASTRA_RESOURCE_ID_KEY) as string | undefined;
  const resourceId = resourceIdFromContext ?? resourceIdFromParams;

  const workflowObj = mastra.getWorkflowById(workflowId);
  if (!workflowObj) {
    throw new Error(`Workflow ${workflowId} not found`);
  }

  const run = await workflowObj.createRun({ runId, resourceId, ...rest });

  const stream = resumeData
    ? run.resumeStream({ resumeData, ...rest, requestContext })
    : run.stream({ inputData, initialState, ...rest, requestContext });

  if (version === 'v7') {
    return createUIMessageStreamV7<V7UIMessage>({
      execute: async ({ writer }) => {
        for await (const part of toAISdkStream(stream, {
          from: 'workflow',
          version: 'v7',
          includeTextStreamParts,
          sendReasoning,
          sendSources,
        })) {

View on GitHub (pinned to 75dd419e61)

Solutions

Verify the workflowId string matches exactly the key used at registration.
Register the workflow: new Mastra({ workflows: { myWorkflow: myWorkflow } }).
Confirm the server process was restarted after adding the workflow.
Check env/feature flags that conditionally include the workflow in the Mastra config.
Ensure the client and server point at the same Mastra deployment/instance.

Example fix

// before
export const mastra = new Mastra({ agents: { weatherAgent } });
client.getWorkflowStream('dataPipeline', ...);
// after
export const mastra = new Mastra({ agents: { weatherAgent }, workflows: { dataPipeline } });
client.getWorkflowStream('dataPipeline', ...);

Defensive patterns

Strategy: try-catch

Validate before calling

const workflows = mastra.listWorkflows();
if (!(workflowId in workflows)) {
  throw new Error(`Workflow '${workflowId}' not registered. Available: ${Object.keys(workflows).join(', ')}`);
}

Type guard

function isRegisteredWorkflow(mastra: Mastra, id: string): boolean {
  return id in mastra.listWorkflows();
}

Try / catch

try {
  const stream = await client.getWorkflowStream(workflowId, ...);
} catch (e) {
  if (e instanceof Error && /Workflow .* not found/.test(e.message)) {
    console.error(`Workflow '${workflowId}' missing on server. Check registration in new Mastra({ workflows: {...} })`);
  } else throw e;
}

Prevention

Keep workflow IDs in a shared constants module used by both server registration and client calls.
List registered workflows at server startup and log them.
Verify registration is not gated behind env flags that differ between environments.

When it happens

Trigger: Calling the workflow stream endpoint (stream/uiMessageStream client methods) with a workflowId that is not registered on the Mastra instance, e.g. mastra.getWorkflowById('myFlow') returning undefined.

Common situations: Typo in the workflow ID between client and server registration; workflow defined but forgotten in the workflows map passed to new Mastra({...}); registration happening after server startup or behind an env-gated config that skipped it; calling across packages where the workflow lives in another Mastra instance.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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