{"record":{"id":"e5e0d879d77f4e67","repo":"mastra-ai/mastra","slug":"dynamic-workflow-references-agent-entry-agentid","errorCode":null,"errorMessage":"Dynamic workflow references agent \"${entry.agentId}\" which is not registered on this Mastra instance.","messagePattern":"Dynamic workflow references agent \"(.+?)\" which is not registered on this Mastra instance\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/core/src/workflows/dynamic/rehydrate.ts","lineNumber":260,"sourceCode":" * execution time (`runAgentEntry` / `runToolEntry`) — so no fake `Step`\n * wrapper is needed and the stored `id` / `outputSchema` / `retries` /\n * `metadata` round-trip losslessly in every position (top-level, parallel,\n * branch, foreach and loop bodies).\n *\n * `step` descriptors resolve agent-then-tool by id against the live Mastra\n * instance; `workflow` entries resolve the registered instance. Both become\n * plain `{ type: 'step' }` entries, same as the fluent builder emits.\n */\nfunction rehydrateSingleEntry(\n  entry: SerializedSingleStepEntry,\n  mastra: Mastra,\n  schemaOpts?: JsonSchemaToZodOptions,\n): SingleStepEntry {\n  switch (entry.type) {\n    case 'agent': {\n      const agent = tryGetAgentById(mastra, entry.agentId);\n      if (!agent) {\n        throw new Error(\n          `Dynamic workflow references agent \"${entry.agentId}\" which is not registered on this Mastra instance.`,\n        );\n      }\n      return {\n        type: 'agent',\n        id: entry.id,\n        agentId: entry.agentId,\n        agent,\n        options: rebuildAgentOptions(entry, schemaOpts),\n      };\n    }\n    case 'tool': {\n      const tool = mastra.getTool?.(entry.toolId);\n      if (!tool) {\n        throw new Error(\n          `Dynamic workflow references tool \"${entry.toolId}\" which is not registered on this Mastra instance.`,\n        );\n      }","sourceCodeStart":242,"sourceCodeEnd":278,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/workflows/dynamic/rehydrate.ts#L242-L278","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Register the missing agent on the Mastra instance: `new Mastra({ agents: { '<agentId>': myAgent } })` before rehydrating.","Verify the stored `agentId` matches the registered key exactly (case-sensitive, no drift from renames).","If rehydrating on another service, share the agent registry or copy the agent definitions there.","Pre-rehydrate, check `mastra.getAgent(entry.agentId)` exists for every agent entry in the stored graph."],"exampleFix":"// before\nconst mastra = new Mastra({}); // workflow references 'weatherAgent'\n\n// after\nconst mastra = new Mastra({ agents: { weatherAgent } });","handlingStrategy":"validation","validationCode":"function assertAgentsRegistered(stored, mastra) {\n  for (const e of stored.entries) {\n    if (e.type === 'agent' && !mastra.getAgent(e.agentId)) {\n      throw new Error(`Agent \"${e.agentId}\" must be registered before rehydration`);\n    }\n  }\n}","typeGuard":"function agentIsRegistered(mastra: Mastra, agentId: string): boolean {\n  return !!mastra.getAgent?.(agentId);\n}","tryCatchPattern":"try {\n  const wf = rehydrateWorkflow(stored, mastra);\n} catch (err) {\n  const m = err instanceof Error && err.message.match(/references agent \"([^\"]+)\" which is not registered/);\n  if (m) throw new Error(`Register agent '${m[1]}' on this Mastra instance before rehydrating.`);\n  throw err;\n}","preventionTips":["Keep a single shared agent registry module imported by every service that rehydrates stored workflows.","Avoid renaming agent ids without migrating stored graphs.","Add a startup check that all agent ids referenced by stored graphs are registered."],"tags":["workflow","agent","registration","rehydration"],"backgroundTag":"unregistered-resource-reference","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}