mastra-ai/mastra · error · Error

Dynamic workflow references nested workflow "${workflowId}"

Error message

Dynamic workflow references nested workflow "${workflowId}" which is not registered on this Mastra instance.

What it means

`assertWorkflowExists` is the shared lookup used when a stored dynamic workflow references a nested workflow by `workflowId`. If `tryGetWorkflowById` finds nothing on the Mastra instance, rehydration aborts with this error because nested workflow execution requires the actual registered workflow object.

Source

Thrown at packages/core/src/workflows/dynamic/rehydrate.ts:398

  if (typeof (mastra as any).getWorkflowById === 'function') {
    try {
      return (mastra as any).getWorkflowById(id);
    } catch {
      // fall through to registration-key lookup
    }
  }
  if (typeof (mastra as any).getWorkflow !== 'function') return undefined;
  try {
    return (mastra as any).getWorkflow(id);
  } catch {
    return undefined;
  }
}

function assertWorkflowExists(mastra: Mastra, workflowId: string): any {
  const wf = tryGetWorkflowById(mastra, workflowId);
  if (!wf) {
    throw new Error(
      `Dynamic workflow references nested workflow "${workflowId}" which is not registered on this Mastra instance.`,
    );
  }
  return wf;
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Register the nested workflow: `new Mastra({ workflows: { '<workflowId>': nestedWf } })` before rehydrating.
2. Verify stored `workflowId` values match registered keys exactly after renames.
3. Ensure all services that rehydrate the graph register the full set of referenced workflows.
4. Pre-validate: for each stored workflow entry, assert `mastra.getWorkflow(workflowId)` exists.

Example fix

// before
const mastra = new Mastra({}); // graph nests workflowId 'childWf'

// after
const mastra = new Mastra({ workflows: { childWf } });

function assertNestedWorkflowsRegistered(stored, mastra) {
  const visit = (e) => {
    if (!e) return;
    if (e.type === 'workflow' && !mastra.getWorkflow?.(e.workflowId)) {
      throw new Error(`Nested workflow "${e.workflowId}" must be registered before rehydration`);
    }
    (e.steps ?? []).forEach(visit);
  };
  stored.entries.forEach(visit);
}

function nestedWorkflowResolves(mastra: Mastra, workflowId: string): boolean {
  return !!mastra.getWorkflow?.(workflowId);
}

try {
  const wf = rehydrateWorkflow(stored, mastra);
} catch (err) {
  const m = err instanceof Error && err.message.match(/nested workflow "([^"]+)" which is not registered/);
  if (m) throw new Error(`Register nested workflow '${m[1]}' on this Mastra instance.`);
  throw err;
}

When it happens

Trigger: rehydrateWorkflow (or a nested entry via rehydrateSingleEntry case 'workflow') references `entry.workflowId` that is absent from `new Mastra({ workflows: {...} })` — removed, renamed, or deployed to an instance that never registered it.

Common situations: Multi-service deployments where the nested workflow lives in another service; renaming workflow ids in refactors; conditional registration of workflows per environment.

Related errors

• Dynamic workflow references agent "${entry.agentId}" which i
• Dynamic workflow references tool "${entry.toolId}" which is
• Dynamic workflow references step "${id}" which is not regist
• Mapping references unknown workflow init-data "${source.init
• Workflow ${workflowId} not found

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