{"record":{"id":"c86dcebebe956740","repo":"mastra-ai/mastra","slug":"mastra-get-tool-by-id-not-found","errorCode":"MASTRA_GET_TOOL_BY_ID_NOT_FOUND","errorMessage":"Tool with id ${id} not found","messagePattern":"Tool with id (.+?) not found","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/core/src/mastra/index.ts","lineNumber":4233,"sourceCode":"   *\n   * @throws {MastraError} When the specified tool is not found\n   *\n   * @example\n   * ```typescript\n   * const mastra = new Mastra({\n   *   tools: {\n   *     calculator: calculatorTool\n   *   }\n   * });\n   *\n   * const tool = mastra.getToolById('calculator-tool-id');\n   * ```\n   */\n  public getToolById<TToolName extends keyof TTools>(id: TTools[TToolName]['id']): TTools[TToolName] {\n    const allTools = this.#tools;\n\n    if (!allTools) {\n      throw new MastraError({\n        id: 'MASTRA_GET_TOOL_BY_ID_NOT_FOUND',\n        domain: ErrorDomain.MASTRA,\n        category: ErrorCategory.USER,\n        text: `Tool with id ${id} not found`,\n      });\n    }\n    // First try to find by internal ID\n    for (const tool of Object.values(allTools)) {\n      if (tool.id === id) {\n        return tool as TTools[TToolName];\n      }\n    }\n\n    // Fallback to searching by registration key\n    const toolByKey = allTools[id];\n    if (toolByKey) {\n      return toolByKey as TTools[TToolName];\n    }","sourceCodeStart":4215,"sourceCodeEnd":4251,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/mastra/index.ts#L4215-L4251","documentation":"getToolById reads the Mastra instance's internal tool registry (#tools). If no tools were registered at all, it throws this MastraError rather than returning undefined, so callers get a clear signal that the tool set is empty. Any id lookup necessarily fails when there are no tools to search.","triggerScenarios":"Calling mastra.getToolById(id) on a Mastra instance constructed without any tools (no tools in the constructor config and none registered later), regardless of the id passed.","commonSituations":"Fetching tools in a script/plugin against a Mastra instance that registers tools only in a different entrypoint; tools configured via environment-dependent code paths; forgetting to pass tools to the Mastra constructor in a trimmed deployment.","solutions":["Register tools (constructor config or registerTool) before calling getToolById.","Use the same Mastra instance/entrypoint that actually has the tools registered.","Guard the call: only fetch by id when tools are registered, or handle the throw as an empty-registry condition.","Verify with the tools listing accessor that the registry is non-empty first."],"exampleFix":"// before\nconst mastra = new Mastra({ agents, workflows });\nconst weather = mastra.getToolById('weatherTool'); // throws: registry empty\n// after\nconst mastra = new Mastra({ agents, workflows, tools: { weatherTool } });\nconst weather = mastra.getToolById('weatherTool');","handlingStrategy":"try-catch","validationCode":"const allTools = mastra.getTools?.();\nif (!allTools || Object.keys(allTools).length === 0) {\n  throw new Error('No tools registered on this Mastra instance; getToolById cannot succeed');\n}","typeGuard":null,"tryCatchPattern":"try {\n  const tool = mastra.getToolById(id);\n} catch (e) {\n  if (e instanceof MastraError && e.id === 'MASTRA_GET_TOOL_BY_ID_NOT_FOUND') {\n    // empty registry: skip tool resolution or use a fallback instance\n  } else throw e;\n}","preventionTips":["Always register tools on the Mastra instance you query, not a different entrypoint's instance.","Add a smoke test asserting the expected tool ids resolve from the real instance.","Log the tool registry at startup in dev to catch empty/missing registrations early."],"tags":["lookup-failed","tools","empty-registry"],"backgroundTag":"resource-not-found","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}