mastra-ai/mastra · error · Error

Dynamic workflow references agent "${entry.agentId}" which i

Error message

Dynamic workflow references agent "${entry.agentId}" which is not registered on this Mastra instance.

What it means

During rehydration of a dynamic workflow, an 'agent' entry references an agent by `agentId` that must exist on the target Mastra instance. If `tryGetAgentById` returns nothing, the library throws because it cannot construct the referenced agent step. Stored workflows are portable definitions; all referenced resources must be registered in the runtime that rehydrates them.

Source

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

 * execution time (`runAgentEntry` / `runToolEntry`) — so no fake `Step`
 * wrapper is needed and the stored `id` / `outputSchema` / `retries` /
 * `metadata` round-trip losslessly in every position (top-level, parallel,
 * branch, foreach and loop bodies).
 *
 * `step` descriptors resolve agent-then-tool by id against the live Mastra
 * instance; `workflow` entries resolve the registered instance. Both become
 * plain `{ type: 'step' }` entries, same as the fluent builder emits.
 */
function rehydrateSingleEntry(
  entry: SerializedSingleStepEntry,
  mastra: Mastra,
  schemaOpts?: JsonSchemaToZodOptions,
): SingleStepEntry {
  switch (entry.type) {
    case 'agent': {
      const agent = tryGetAgentById(mastra, entry.agentId);
      if (!agent) {
        throw new Error(
          `Dynamic workflow references agent "${entry.agentId}" which is not registered on this Mastra instance.`,
        );
      }
      return {
        type: 'agent',
        id: entry.id,
        agentId: entry.agentId,
        agent,
        options: rebuildAgentOptions(entry, schemaOpts),
      };
    }
    case 'tool': {
      const tool = mastra.getTool?.(entry.toolId);
      if (!tool) {
        throw new Error(
          `Dynamic workflow references tool "${entry.toolId}" which is not registered on this Mastra instance.`,
        );
      }

View on GitHub (pinned to 75dd419e61)

Solutions

1. Register the missing agent on the Mastra instance: `new Mastra({ agents: { '<agentId>': myAgent } })` before rehydrating.
2. Verify the stored `agentId` matches the registered key exactly (case-sensitive, no drift from renames).
3. If rehydrating on another service, share the agent registry or copy the agent definitions there.
4. Pre-rehydrate, check `mastra.getAgent(entry.agentId)` exists for every agent entry in the stored graph.

Example fix

// before
const mastra = new Mastra({}); // workflow references 'weatherAgent'

// after
const mastra = new Mastra({ agents: { weatherAgent } });

function assertAgentsRegistered(stored, mastra) {
  for (const e of stored.entries) {
    if (e.type === 'agent' && !mastra.getAgent(e.agentId)) {
      throw new Error(`Agent "${e.agentId}" must be registered before rehydration`);
    }
  }
}

function agentIsRegistered(mastra: Mastra, agentId: string): boolean {
  return !!mastra.getAgent?.(agentId);
}

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

When it happens

Trigger: rehydrateWorkflow is called on a Mastra instance where an agent with the stored `entry.agentId` was never registered via `new Mastra({ agents: {...} })`, or the id was renamed/removed, or the entry comes from a different deployment whose agent registry differs.

Common situations: Deploying a stored workflow to a service that doesn't register all agents; renaming agent ids during a refactor; multi-tenant setups where agents are conditionally registered; forgetting to import an agent module.

Related errors

• 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
• Dynamic workflow references nested workflow "${workflowId}"
• Workflow ${workflowId} not found

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