What causes "Tool with id ${id} not found" in mastra-ai/mastra?

Register tools (constructor config or registerTool) before calling getToolById.

mastra-ai/mastra · error · MastraError

MASTRA_GET_TOOL_BY_ID_NOT_FOUND

MASTRA_GET_TOOL_BY_ID_NOT_FOUND

Error message

Tool with id ${id} not found

What it means

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.

Source

Thrown at packages/core/src/mastra/index.ts:4233

   *
   * @throws {MastraError} When the specified tool is not found
   *
   * @example
   * ```typescript
   * const mastra = new Mastra({
   *   tools: {
   *     calculator: calculatorTool
   *   }
   * });
   *
   * const tool = mastra.getToolById('calculator-tool-id');
   * ```
   */
  public getToolById<TToolName extends keyof TTools>(id: TTools[TToolName]['id']): TTools[TToolName] {
    const allTools = this.#tools;

    if (!allTools) {
      throw new MastraError({
        id: 'MASTRA_GET_TOOL_BY_ID_NOT_FOUND',
        domain: ErrorDomain.MASTRA,
        category: ErrorCategory.USER,
        text: `Tool with id ${id} not found`,
      });
    }
    // First try to find by internal ID
    for (const tool of Object.values(allTools)) {
      if (tool.id === id) {
        return tool as TTools[TToolName];
      }
    }

    // Fallback to searching by registration key
    const toolByKey = allTools[id];
    if (toolByKey) {
      return toolByKey as TTools[TToolName];
    }

View on GitHub (pinned to 75dd419e61)

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.

Example fix

// before
const mastra = new Mastra({ agents, workflows });
const weather = mastra.getToolById('weatherTool'); // throws: registry empty
// after
const mastra = new Mastra({ agents, workflows, tools: { weatherTool } });
const weather = mastra.getToolById('weatherTool');

Defensive patterns

Strategy: try-catch

Validate before calling

const allTools = mastra.getTools?.();
if (!allTools || Object.keys(allTools).length === 0) {
  throw new Error('No tools registered on this Mastra instance; getToolById cannot succeed');
}

Try / catch

try {
  const tool = mastra.getToolById(id);
} catch (e) {
  if (e instanceof MastraError && e.id === 'MASTRA_GET_TOOL_BY_ID_NOT_FOUND') {
    // empty registry: skip tool resolution or use a fallback instance
  } else throw e;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/c86dcebebe956740. Report an issue: GitHub.