{"record":{"id":"737771ff1bf6b6d2","repo":"mastra-ai/mastra","slug":"agent-entry-agentid-not-found-for-workflow-st","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":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/workflows/default.ts","lineNumber":1203,"sourceCode":"\n  async executeSleepUntil(params: ExecuteSleepUntilParams): Promise<void> {\n    return executeSleepUntilHandler(this, params);\n  }\n\n  async executeStep(params: ExecuteStepParams): Promise<StepExecutionResult> {\n    return executeStepHandler(this, params);\n  }\n\n  /**\n   * Executes a declarative `agent` step: resolves the agent (live ref, else\n   * `mastra.getAgentById(agentId)`), builds its runnable step, and runs it through\n   * the shared step runner.\n   */\n  async executeAgent(params: ExecuteAgentParams): Promise<StepExecutionResult> {\n    const { entry, ...rest } = params;\n    const agent = entry.agent ?? this.mastra?.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    return this.executeStep({ ...rest, step: { ...createStepFromAgent(agent as any, entry.options), id: entry.id } });\n  }\n\n  /**\n   * Executes a declarative `tool` step: resolves the tool (live ref, else\n   * `mastra.getTool(toolId)`), builds its runnable step, and runs it through the\n   * shared step runner.\n   */\n  async executeTool(params: ExecuteToolParams): Promise<StepExecutionResult> {\n    const { entry, ...rest } = params;\n    const tool = entry.tool ?? this.mastra?.getTool(entry.toolId);\n    if (!tool) {\n      throw new Error(\n        `Tool '${entry.toolId}' not found for workflow step '${entry.id}'. Pass the tool instance directly.`,\n      );","sourceCodeStart":1185,"sourceCodeEnd":1221,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/workflows/default.ts#L1185-L1221","documentation":"When a workflow definition references an agent by string id, executeAgent resolves it via mastra.getAgentById at run time. If no agent instance was passed directly and the id is not registered on the Mastra instance, execution of the step throws this error.","triggerScenarios":"A dynamic/stored workflow graph entry `{ type: 'agent', agentId: 'myAgent' }` executes while: the agent was never registered via `new Mastra({ agents: { myAgent } })`, the id is misspelled, the agent was registered after workflow execution started, or the workflow runs without a Mastra instance attached.","commonSituations":"Renaming an agent without updating stored workflow definitions; deploying workflows to a service that registers a different agent set; running rehydrated workflows from storage against a fresh Mastra instance missing that agent; typo in agentId in a builder UI export.","solutions":["Register the agent on the Mastra instance: new Mastra({ agents: { myAgent } }).","Pass the agent instance directly in the step entry (`entry.agent`) instead of relying on agentId resolution.","Fix the agentId string to match the registered agent, and update any stored workflow definitions in the DB."],"exampleFix":"// before\nnew Mastra({ workflows: { myWorkflow } }) // agent 'myAgent' never registered\n// after\nnew Mastra({ agents: { myAgent: myAgent }, workflows: { myWorkflow } })","handlingStrategy":"validation","validationCode":"const agent = entry.agent ?? mastra.getAgentById?.(entry.agentId);\nif (!agent) {\n  throw new Error(`Agent '${entry.agentId}' is not registered on the Mastra instance before running the workflow`);\n}","typeGuard":"function agentIsResolvable(entry: { agent?: unknown; agentId?: string }, mastra: Mastra): boolean {\n  return Boolean(entry.agent) || Boolean(entry.agentId && mastra.getAgentById(entry.agentId));\n}","tryCatchPattern":"try {\n  await workflow.start({ inputData });\n} catch (e) {\n  if (e instanceof Error && e.message.includes(\"not found for workflow step\")) {\n    // register the missing agent or fix agentId, then retry\n  }\n  throw e;\n}","preventionTips":["Register every referenced agent on the Mastra instance at startup.","Verify ids with mastra.getAgentById(id) before persisting definitions.","Pass agent instances directly for dynamic workflows when possible.","Add a startup check that all agentIds in stored workflows resolve."],"tags":["workflow","agent","runtime-lookup"],"backgroundTag":"resource-not-registered","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}