{"record":{"id":"d8c9393794531742","repo":"mastra-ai/mastra","slug":"tool-entry-toolid-not-found-for-workflow-step","errorCode":null,"errorMessage":"Tool '${entry.toolId}' not found for workflow step '${entry.id}'. Pass the tool instance directly.","messagePattern":"Tool '(.+?)' not found for workflow step '(.+?)'\\. Pass the tool instance directly\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/core/src/workflows/default.ts","lineNumber":1219,"sourceCode":"    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      );\n    }\n    return this.executeStep({ ...rest, step: { ...createStepFromTool(tool as any, entry.options), id: entry.id } });\n  }\n\n  /**\n   * Executes a declarative `mapping` step: builds the mapping step from the\n   * declarative config/fn and runs it through the shared step runner.\n   */\n  async executeMapping(params: ExecuteMappingParams): Promise<StepExecutionResult> {\n    const { entry, ...rest } = params;\n    return this.executeStep({ ...rest, step: createMappingStep(entry.id, entry.mapConfig) });\n  }\n\n  async executeParallel(params: ExecuteParallelParams): Promise<StepResult<any, any, any, any>> {\n    return executeParallelHandler(this, params);\n  }","sourceCodeStart":1201,"sourceCodeEnd":1237,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/workflows/default.ts#L1201-L1237","documentation":"executeTool resolves a tool referenced by string id via mastra.getTool at run time. If no tool instance was passed directly on the step entry and the id is not found on the Mastra instance, the step throws this error. Unlike agents, there is no registry fallback suggested — the message says to pass the tool instance directly.","triggerScenarios":"A dynamic/stored workflow graph entry `{ type: 'tool', toolId: 'weatherTool' }` executes while the tool is not registered on the Mastra instance (`new Mastra({ tools: { weatherTool } })` missing or misspelled), or the workflow has no Mastra instance reference.","commonSituations":"Stored workflow definitions referencing tools that were deleted or renamed; tools defined locally in a file but never attached to Mastra; importing a workflow definition from another project where the tool doesn't exist; typo in toolId.","solutions":["Register the tool on the Mastra instance: new Mastra({ tools: { weatherTool } }).","Pass the tool instance directly on the step entry (`entry.tool`) so no id lookup is needed.","Correct the toolId string in the definition/stored graph."],"exampleFix":"// before\n{ type: 'tool', id: 'step1', toolId: 'weatherTool' } // tool not registered\n// after\nnew Mastra({ tools: { weatherTool } }) // or: { type: 'tool', id: 'step1', tool: weatherTool }","handlingStrategy":"validation","validationCode":"const tool = entry.tool ?? mastra.getTool?.(entry.toolId);\nif (!tool) {\n  throw new Error(`Tool '${entry.toolId}' is not registered on the Mastra instance before running the workflow`);\n}","typeGuard":"function toolIsResolvable(entry: { tool?: unknown; toolId?: string }, mastra: Mastra): boolean {\n  return Boolean(entry.tool) || Boolean(entry.toolId && mastra.getTool(entry.toolId));\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 tool or pass the tool instance, then retry\n  }\n  throw e;\n}","preventionTips":["Register all referenced tools via new Mastra({ tools: {...} }).","Pass tool instances directly on step entries in dynamic workflows.","Validate toolIds in stored graphs resolve before executing.","Grep definitions for toolIds and diff against the registered tool set in CI."],"tags":["workflow","tool","runtime-lookup"],"backgroundTag":"resource-not-registered","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}