{"record":{"id":"1f7d3a275466db4c","repo":"mastra-ai/mastra","slug":"agent-entry-agentid-not-found-for-workflow-st-1f7d3a","errorCode":null,"errorMessage":"Agent '${entry.agentId}' not found for workflow step '${entry.id}'. Register the agent on the Mastra instance or pass the agent instance directly.","messagePattern":"Agent '(.+?)' not found for workflow step '(.+?)'\\. Register the agent on the Mastra instance or pass the agent instance directly\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/core/src/workflows/entry-executors/run-agent-entry.ts","lineNumber":29,"sourceCode":"import type { EntryExecuteContext } from './types';\n\n/**\n * Runs a declarative `agent` entry: resolves the agent (inline handle, else the\n * Mastra registry), streams the prompt through it, forwards stream chunks, and\n * returns either the structured output or `{ text }`.\n *\n * `ctx` is the step execute context (the same object a plain step's `execute`\n * receives). `mastra` defaults to `ctx.mastra` when omitted.\n */\nexport async function runAgentEntry(\n  entry: AgentStepEntry,\n  ctx: EntryExecuteContext,\n  mastra?: Mastra,\n): Promise<unknown> {\n  const registry = mastra ?? (ctx?.mastra as Mastra | undefined);\n  const agent = entry.agent ?? registry?.getAgentById(entry.agentId);\n  if (!agent) {\n    throw new Error(\n      `Agent '${entry.agentId}' not found for workflow step '${entry.id}'. Register the agent on the Mastra instance or pass the agent instance directly.`,\n    );\n  }\n\n  // `retries` / `scorers` / `metadata` are step-level concerns handled by the\n  // engine (see getEntryRetries); everything else is passed to the agent run.\n  const { retries: _retries, scorers: _scorers, metadata: _metadata, ...agentOptions } = (entry.options ?? {}) as any;\n\n  const {\n    inputData,\n    runId,\n    [PUBSUB_SYMBOL]: pubsub,\n    [STREAM_FORMAT_SYMBOL]: streamFormat,\n    requestContext,\n    actor,\n    abortSignal,\n    abort,\n    writer,","sourceCodeStart":11,"sourceCodeEnd":47,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/workflows/entry-executors/run-agent-entry.ts#L11-L47","documentation":"A workflow step references an agent by agentId, but neither an agent instance on the step entry nor an agent registered under that id on the Mastra instance could be resolved at execution time. runAgentEntry throws this Error before running the step because it cannot obtain the Agent to invoke.","triggerScenarios":"Executing a (dynamic) workflow whose step entry has agentId set but entry.agent undefined, while mastra.getAgentById(entry.agentId) returns undefined — i.e. the agent was never registered on the Mastra instance (or ctx.mastra is missing).","commonSituations":"Dynamic workflows created by codegen/LLM referencing agent ids that were never registered; agent registered with a different id/key than referenced; running the workflow engine without passing the Mastra instance (mastra argument and ctx.mastra both undefined); typos in agentId after renaming agents.","solutions":["Register the agent on the Mastra instance: new Mastra({ agents: { myAgentId: myAgent } }) so getAgentById can find it.","Or pass the agent instance directly on the step entry: { id: 'step', agent: myAgent } instead of only agentId.","Verify the agentId string exactly matches the registration key (check for typos/casing).","Ensure the Mastra instance is available to the workflow engine (pass it as the mastra param or attach ctx.mastra)."],"exampleFix":"// before\nsteps: [{ id: 'summarize', agentId: 'summarizer' }] // 'summarizer' never registered\n// after\nnew Mastra({ agents: { summarizer: new Agent({ name: 'summarizer', ... }) }) }\n// or: steps: [{ id: 'summarize', agent: summarizerAgent }]","handlingStrategy":"validation","validationCode":"const agent = entry.agent ?? mastra?.getAgentById(entry.agentId);\nif (!agent) throw new Error(`Step '${entry.id}' references unregistered agent '${entry.agentId}'`);","typeGuard":"function hasAgent(entry: { agent?: unknown; agentId: string }, mastra?: Mastra): boolean {\n  return !!entry.agent || !!mastra?.getAgentById(entry.agentId);\n}","tryCatchPattern":"try { await runAgentEntry(entry, ctx, mastra); } catch (e) { if (e instanceof Error && e.message.includes(\"not found for workflow step\")) { registerMissingAgent(entry.agentId); } else throw e; }","preventionTips":["Register every referenced agent on the Mastra instance at startup.","Prefer passing agent instances directly on step entries for dynamic workflows.","Keep agent ids in a shared constants module to avoid typos.","Assert all workflow agent references resolve before running (dry validation)."],"tags":["workflows","agents","configuration","registry"],"backgroundTag":"agent-not-registered","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}