mastra-ai/mastra · error · HTTPException

Schema for tool ${toolSlug} not found in provider ${provider

Error message

Schema for tool ${toolSlug} not found in provider ${providerId}

What it means

HTTP 404 thrown when provider.getToolSchema(toolSlug) returns a falsy value — the provider supports schemas but has no schema registered under the requested tool slug. The handler converts the null/undefined result into a 404 naming both the tool and the provider.

Source

Thrown at packages/server/src/server/handlers/tool-providers.ts:247

  method: 'GET',
  path: '/tool-providers/:providerId/tools/:toolSlug/schema',
  responseType: 'json',
  pathParamSchema: toolSlugPathParams,
  responseSchema: getToolProviderToolSchemaResponseSchema,
  summary: 'Get tool provider tool schema',
  description: 'Returns the schema for a specific tool from a tool provider',
  tags: ['Tool Providers'],
  requiresAuth: true,
  handler: async ({ mastra, providerId, toolSlug }) => {
    try {
      const editor = requireEditor(mastra.getEditor());
      const provider = await resolveProvider(editor, providerId);
      if (!provider.getToolSchema) {
        throw new HTTPException(404, { message: `Tool provider ${providerId} does not support getToolSchema` });
      }
      const schema = await provider.getToolSchema(toolSlug);
      if (!schema) {
        throw new HTTPException(404, { message: `Schema for tool ${toolSlug} not found in provider ${providerId}` });
      }
      return schema;
    } catch (error) {
      return handleError(error, 'Error getting tool provider tool schema');
    }
  },
});

/**
 * POST /tool-providers/:providerId/authorize — Start an OAuth flow and persist
 * a `tool_provider_connections` row for label / scope joins.
 */
export const AUTHORIZE_TOOL_PROVIDER_ROUTE = createRoute({
  method: 'POST',
  path: '/tool-providers/:providerId/authorize',
  responseType: 'json',
  pathParamSchema: toolProviderIdPathParams,
  bodySchema: authorizeToolProviderBodySchema,

View on GitHub (pinned to 75dd419e61)

Solutions

Verify toolSlug against the provider's listTools() output and use the exact slug.
Refresh the tool list from listTools instead of using cached slugs.
Add the missing tool schema to the provider's getToolSchema implementation if the tool should exist.
Check whether the tool belongs to a different registered providerId.

Example fix

// before
const schema = await api.getToolSchema('acme', 'send-email-v2');
// after
const tools = await api.listProviderTools('acme');
const slug = tools.find(t => t.name === 'Send Email')?.slug; // 'send-email-v3'
const schema = slug ? await api.getToolSchema('acme', slug) : null;

Defensive patterns

Strategy: validation

Validate before calling

const tools = await api.listProviderTools(providerId);
if (!tools.some(t => t.slug === toolSlug)) {
  throw new Error(`Tool '${toolSlug}' not offered by provider '${providerId}'`);
}

Try / catch

try {
  return await api.getToolSchema(providerId, toolSlug);
} catch (e) {
  if (e.status === 404 && /Schema for tool .* not found/.test(e.message)) return null;
  throw e;
}

Prevention

Always derive tool slugs from listTools(), never hardcode them.
Invalidate cached tool lists after provider upgrades.
Watch for slug casing/whitespace differences between providers.

When it happens

Trigger: GET /api/tool-providers/:providerId/tools/:toolSlug/schema where toolSlug is not present in the provider's schema map (tool-providers.ts:247).

Common situations: Typo or outdated toolSlug from a stale playground cache; provider updated and the tool renamed/removed; requesting a tool that belongs to a different provider; case-sensitivity mismatch in slugs.

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/cabc6224b9e30b67. Report an issue: GitHub.