{"record":{"id":"3842414e163fcaa3","repo":"mastra-ai/mastra","slug":"tool-entry-toolid-not-found-for-workflow-step-384241","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/entry-executors/run-tool-entry.ts","lineNumber":16,"sourceCode":"import type { Mastra } from '../../mastra';\nimport { resolveObservabilityContext } from '../../observability';\nimport type { ToolStepEntry } from '../types';\nimport { resolveEntryActor } from './actor';\nimport type { EntryExecuteContext } from './types';\n\n/**\n * Runs a declarative `tool` entry: resolves the tool (inline handle, else the\n * Mastra registry) and executes it with the step context mapped into the tool\n * execution context.\n */\nexport async function runToolEntry(entry: ToolStepEntry, ctx: EntryExecuteContext, mastra?: Mastra): Promise<unknown> {\n  const registry = mastra ?? (ctx?.mastra as Mastra | undefined);\n  const tool = entry.tool ?? registry?.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\n  const {\n    inputData,\n    mastra: ctxMastra,\n    requestContext,\n    suspend,\n    resumeData,\n    runId,\n    workflowId,\n    state,\n    setState,\n    abortSignal,\n    actor,\n    ...rest\n  } = ctx;","sourceCodeStart":1,"sourceCodeEnd":34,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/workflows/entry-executors/run-tool-entry.ts#L1-L34","documentation":"A workflow step references a tool by toolId, but neither an instance on the step entry (entry.tool) nor a tool registered under that id on the Mastra instance could be resolved. runToolEntry throws this Error before executing the step.","triggerScenarios":"Executing a (dynamic) workflow whose ToolStepEntry has toolId set but entry.tool undefined, while registry.getTool(entry.toolId) returns undefined — the tool was never registered on the Mastra instance or the id is wrong.","commonSituations":"Dynamic/codegen workflows referencing tool ids that were not registered; tools created locally but not passed to Mastra; typos or renamed tool ids; running the engine without the Mastra instance in scope.","solutions":["Register the tool on the Mastra instance: new Mastra({ tools: { myToolId: myTool } }).","Or pass the tool instance directly on the step entry: { id: 'step', tool: myTool } (note the message says instance is required here, unlike agents).","Verify toolId matches the registration key exactly.","Ensure the Mastra instance is reachable by the engine (mastra param or ctx.mastra)."],"exampleFix":"// before\nsteps: [{ id: 'fetch', toolId: 'fetchWeather' }] // never registered\n// after\nsteps: [{ id: 'fetch', tool: createTool({ id: 'fetchWeather', ... }) }]\n// or: new Mastra({ tools: { fetchWeather: weatherTool } })","handlingStrategy":"validation","validationCode":"const tool = entry.tool ?? mastra?.getTool(entry.toolId);\nif (!tool) throw new Error(`Step '${entry.id}' references unregistered tool '${entry.toolId}'`);","typeGuard":"function hasTool(entry: { tool?: unknown; toolId: string }, mastra?: Mastra): boolean {\n  return !!entry.tool || !!mastra?.getTool(entry.toolId);\n}","tryCatchPattern":"try { await runToolEntry(entry, ctx, mastra); } catch (e) { if (e instanceof Error && e.message.includes(\"Tool '\") && e.message.includes(\"not found\")) { attachToolInstance(entry); } else throw e; }","preventionTips":["Pass tool instances directly on dynamic workflow step entries (registration alone is not enough here).","Register shared tools on the Mastra instance for id-based lookup.","Centralize tool id constants to avoid drift.","Validate all tool references resolve before executing a dynamic workflow."],"tags":["workflows","tools","configuration","registry"],"backgroundTag":"tool-not-registered","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}