mastra-ai/mastra · error · HTTPException

Tool provider ${providerId} does not support getToolSchema

Error message

Tool provider ${providerId} does not support getToolSchema

What it means

HTTP 404 thrown by the get-tool-schema handler when the resolved ToolProvider exists but does not implement the optional getToolSchema method. The Mastra ToolProvider interface makes schema lookup optional, so providers that only supply auth/connections cannot serve per-tool schemas.

Source

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

/**
 * GET /tool-providers/:providerId/tools/:toolSlug/schema — Tool schema.
 */
export const GET_TOOL_PROVIDER_TOOL_SCHEMA_ROUTE = createRoute({
  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',

View on GitHub (pinned to 75dd419e61)

Solutions

Implement getToolSchema(toolSlug) on the ToolProvider class and re-register it.
Use a provider that supports tool schemas if the consumer needs them.
Guard the client: check provider capabilities (or catch 404) before requesting a schema.
If the provider should support schemas, check for a newer provider package version that adds getToolSchema.

Example fix

// before
class MyProvider implements ToolProvider { listTools() { /* ... */ } }
// after
class MyProvider implements ToolProvider {
  listTools() { /* ... */ }
  async getToolSchema(toolSlug: string) {
    return this.schemas.get(toolSlug) ?? null;
  }
}

Defensive patterns

Strategy: type-guard

Validate before calling

const provider = await api.getProvider(providerId);
if (typeof provider?.getToolSchema !== 'function') {
  console.warn(`Provider ${providerId} does not support tool schemas`);
}

Type guard

function supportsGetToolSchema(p: ToolProvider): p is ToolProvider & Required<Pick<ToolProvider, 'getToolSchema'>> {
  return typeof p.getToolSchema === 'function';
}

Try / catch

try {
  return await api.getToolSchema(providerId, toolSlug);
} catch (e) {
  if (e.status === 404 && /does not support getToolSchema/.test(e.message)) return null;
  throw e;
}

Prevention

Check provider capabilities before rendering schema-dependent UI.
Document which optional ToolProvider methods each custom provider implements.
Keep provider implementations up to date with the ToolProvider interface.

When it happens

Trigger: GET /api/tool-providers/:providerId/tools/:toolSlug/schema (handler at tool-providers.ts:243) against a provider registered without a getToolSchema implementation.

Common situations: Pointing the playground/schema UI at a custom provider that only implements listTools or authorize; upgrading to a provider version where getToolSchema was removed; using a built-in provider type that intentionally has no schema support.

Related errors

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