No workflow registered with id "${workflowId}". Was it built

Error message

No workflow registered with id "${workflowId}". Was it built and saved?

What it means

runWorkflow first tries mastra.getWorkflow(workflowId); if that throws or returns nothing, no workflow with that id is registered in the instance. The error wraps the original lookup error as cause and hints that the workflow must be built and saved before it can run.

Source

Thrown at mastracode/sdk/src/workflows/service.ts:114

   * emits — used by the `/workflows run` slash handler to render live per-step
   * progress in the TUI. Non-fatal: errors in the callback are swallowed so a
   * misbehaving consumer can't take the workflow down.
   */
  onEvent?: WorkflowRunEventCallback,
): Promise<RunResult> {
  // `getWorkflow` is generic over the statically-registered workflow map, but
  // stored workflows are registered dynamically at load time — the id is a
  // runtime value, not a compile-time key. `as never` widens the arg past the
  // generic constraint; the runtime lookup already validates.
  let wf: ReturnType<Mastra['getWorkflow']> | undefined;
  let lookupError: unknown;
  try {
    wf = mastra.getWorkflow(workflowId as never);
  } catch (error) {
    lookupError = error;
  }
  if (!wf) {
    throw new Error(`No workflow registered with id "${workflowId}". Was it built and saved?`, { cause: lookupError });
  }

  const run = await wf.createRun();
  if (!onEvent) {
    return (await run.start({
      inputData,
      requestContext: requestContext as Parameters<typeof run.start>[0]['requestContext'],
    })) as RunResult;
  }

  const output = run.stream({
    inputData,
    requestContext: requestContext as Parameters<typeof run.stream>[0]['requestContext'],
  }) as unknown as WorkflowRunOutputLike;
  for await (const event of output.fullStream) {
    try {
      onEvent(event);
    } catch {

View on GitHub (pinned to 75dd419e61)

Solutions

Check registered ids with listWorkflows(mastra) and correct the workflowId (typos are the usual cause)
Rebuild and save the workflow so it registers under the expected id
Confirm the workflow's storage row is status 'active'; re-save/activate it if it was deleted or deactivated

Example fix

// before
await runWorkflow(mastra, 'deploy-app', inputData);
// after
const { workflows } = await listWorkflows(mastra);
console.log(workflows.map(w => w.id)); // confirm the exact id first
await runWorkflow(mastra, 'deploy-app-v2', inputData);

Defensive patterns

Strategy: try-catch

Validate before calling

import { listWorkflows } from '.../workflows/service';
const { workflows } = await listWorkflows(mastra);
const known = new Set(workflows.map(w => w.id));
if (!known.has(workflowId)) throw new Error(`Unknown workflow "${workflowId}". Available: ${[...known].join(', ')}`);

Try / catch

try {
  await runWorkflow(mastra, workflowId, inputData);
} catch (e) {
  if (String(e.message).startsWith('No workflow registered with id')) {
    const { workflows } = await listWorkflows(mastra);
    console.error(`Available workflows: ${workflows.map(w => w.id).join(', ')}`);
  } else throw e;
}

Prevention

List registered workflow ids (listWorkflows) and validate user input against them before running
Keep workflow ids in constants or a generated registry to avoid typos
Ensure workflows are built and saved with status 'active' before exposing them to runners

When it happens

Trigger: Calling runWorkflow with a workflowId that was never registered (typo), was deleted from storage, or exists in storage with status != 'active' so it isn't loaded at boot.

Common situations: Renaming a workflow without updating callers; a workflow build/save step failed earlier leaving no registered id; listing filtered by status:'active' while the workflow is inactive/deleted; running against a different Mastra instance than the one that registered it.

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/8948372aa1d00a1b. Report an issue: GitHub.