mastra-ai/mastra · error · MastraError

MASTRA_SERVER_API_INVALID_ROUTE_OPTIONS

MASTRA_SERVER_API_INVALID_ROUTE_OPTIONS

Error message

Invalid options for route "${path}", missing "method" property

What it means

Mastra validates every API route registered via registerApiRoute before mounting it on the Hono server. This error is thrown when the route options object omits the required 'method' property, which tells the server which HTTP verb the route handles. It fails fast at registration time so misconfigured routes never reach the running server.

Source

Thrown at packages/core/src/server/index.ts:98

   */
  cors?: CorsOptions;
  /**
   * When false, skips Mastra auth for this route (defaults to true)
   */
  requiresAuth?: boolean;
  /**
   * Explicit RBAC permission for the route.
   */
  requiresPermission?: ApiRoute['requiresPermission'];
  /**
   * Optional FGA configuration for resource-level authorization.
   */
  fga?: ApiRoute['fga'];
};

function validateOptions<P extends string>(path: P, options: RegisterApiRouteOptions<P>): void {
  if (options.method === undefined) {
    throw new MastraError({
      id: 'MASTRA_SERVER_API_INVALID_ROUTE_OPTIONS',
      text: `Invalid options for route "${path}", missing "method" property`,
      domain: ErrorDomain.MASTRA_SERVER,
      category: ErrorCategory.USER,
    });
  }

  if (options.handler === undefined && options.createHandler === undefined) {
    throw new MastraError({
      id: 'MASTRA_SERVER_API_INVALID_ROUTE_OPTIONS',
      text: `Invalid options for route "${path}", you must define a "handler" or "createHandler" property`,
      domain: ErrorDomain.MASTRA_SERVER,
      category: ErrorCategory.USER,
    });
  }

  if (options.handler !== undefined && options.createHandler !== undefined) {
    throw new MastraError({

View on GitHub (pinned to 75dd419e61)

Solutions

1. Add a 'method' property to the route options with a valid HTTP verb (e.g. method: 'GET').
2. If routes come from external config, validate/transform the config into RegisterApiRouteOptions before calling registerApiRoute.
3. Check for typos such as 'methods' or 'httpMethod' instead of 'method'.

Example fix

// before
registerApiRoute('/users', {
  handler: async (c) => c.json({ ok: true }),
});
// after
registerApiRoute('/users', {
  method: 'GET',
  handler: async (c) => c.json({ ok: true }),
});

function assertRouteHasMethod(path, options) {
  if (options == null || options.method === undefined) {
    throw new TypeError(`Route "${path}" is missing required "method" property`);
  }
}
// call before registerApiRoute(path, options)

function hasMethod(o) {
  return typeof o === 'object' && o !== null && 'method' in o && typeof o.method === 'string';
}

try {
  registerApiRoute(path, options);
} catch (e) {
  if (String(e?.message).includes('missing "method" property')) {
    console.error(`Route ${path} config invalid: add a method`);
  } else throw e;
}

When it happens

Trigger: Calling registerApiRoute(path, {...}) with an options object that lacks a 'method' field entirely — e.g. registerApiRoute('/my-route', { handler: async (c) => c.json({}) }).

Common situations: Hand-writing route configs instead of using the typed RegisterApiRouteOptions helper; building routes dynamically from a plain object (e.g. from JSON config) where the method key was never set; refactoring away from an older route definition style that inferred the method elsewhere.

Related errors

• Cookie password must be at least 32 characters. Set WORKOS_C
• Factory rule version is required.
• ${label} must be an object.
• Factory rules must be an object.
• [QueueHealthStorage] thresholdsSeconds must be a non-empty a

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