mastra-ai/mastra · error · HTTPException

Tool not found

Error message

Tool not found

What it means

A 404 thrown by the GET tool endpoint when a toolId cannot be resolved either from registered tools, the Mastra instance, or the dynamic agents toolsResolver fallback (findToolInAgents). It means no tool with that ID is visible to the current server/request context.

Source

Thrown at packages/server/src/server/handlers/tools.ts:213

      // Try explicit registeredTools first, then fallback to mastra
      if (registeredTools && Object.keys(registeredTools).length > 0) {
        tool = Object.values(registeredTools).find((t: any) => t.id === toolId);
      }
      if (!tool) {
        try {
          tool = mastra.getToolById(toolId);
        } catch {
          // tool not found in global registry, continue to agent fallback
        }
      }

      // Fallback: search dynamically-resolved agent tools (toolsResolver)
      if (!tool) {
        tool = await findToolInAgents(mastra, toolId, requestContext);
      }

      if (!tool) {
        throw new HTTPException(404, { message: 'Tool not found' });
      }

      return serializeTool(tool);
    } catch (error) {
      return handleError(error, 'Error getting tool');
    }
  },
});

export const EXECUTE_TOOL_ROUTE = createRoute({
  method: 'POST',
  path: '/tools/:toolId/execute',
  responseType: 'json',
  pathParamSchema: toolIdPathParams,
  queryParamSchema: optionalRunIdSchema,
  bodySchema: executeToolContextBodySchema,
  responseSchema: executeToolResponseSchema,
  summary: 'Execute tool',

View on GitHub (pinned to 75dd419e61)

Solutions

1. List available tools (GET /api/tools) and confirm the exact toolId.
2. Register the tool on the Mastra instance or ensure the agent's toolsResolver resolves it for the current request context.
3. Check that any required credentials/context for dynamic tools are present in the request.

Example fix

// before
await api.get('/api/tools/weather_lookup'); // 404 (actual id differs)
// after
const { tools } = await api.get('/api/tools');
const id = tools.find(t => t.description.includes('weather')).id;
await api.get(`/api/tools/${id}`);

const { tools } = await api.get('/api/tools');
if (!tools.some(t => t.id === toolId)) {
  throw new Error(`Tool ${toolId} not available on this server`);
}

try {
  return await api.get(`/api/tools/${toolId}`);
} catch (e) {
  if (e.status === 404) return null;
  throw e;
}

When it happens

Trigger: GET /api/tools/:toolId where toolId doesn't match any registered tool, any tool on the Mastra instance, or any tool produced by dynamically-resolved agent tools (toolsResolver), possibly due to per-request context filtering.

Common situations: Typo'd tool ID or wrong casing; tool only exists on an agent whose toolsResolver depends on request context/credentials; server deployed without the tool registered; tool renamed after upgrade.

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

• Connection ${connectionId} not found for provider ${provider
• Model "${modelId}" is not available. Available models: ${ids
• ACP connection is not initialized
• Model "${this.options.model}" is not available. Available mo
• ClaudeSDKAgent resumeData must include either sessionId or c

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