mastra-ai/mastra · error · Error

[mastra/auth-ee] FGA is configured but ${missingRoutes.lengt

Error message

[mastra/auth-ee] FGA is configured but ${missingRoutes.length} protected route${missingRoutes.length === 1 ? ' is' : 's are'} missing FGA metadata: ${routeList.join(', ')}

What it means

When OpenFGA (FGA) authorization is configured in @mastra/auth-ee, every protected route must declare FGA metadata (relation/permission mapping). The server adapter audits all protected routes at startup; if any lack that metadata, it reports them. In 'error' audit mode it throws, otherwise it logs a warning listing the offending routes.

Source

Thrown at packages/server/src/server/server-adapter/index.ts:937

      await fgaProvider.validatePermissions(permissions);
    }

    const auditMode = fgaProvider.auditProtectedRoutes ?? (fgaProvider.requireForProtectedRoutes ? 'warn' : false);
    if (!auditMode || fgaProvider.resolveRouteFGA) return;

    const missingRoutes = routes.filter(
      route => isProtectedFGARoute(route) && !route.fga && !getBuiltInRouteFGAConfig(route),
    );

    if (missingRoutes.length === 0) return;

    const routeList = missingRoutes.map(route => formatRoute(route as ServerRoute));
    const message =
      `[mastra/auth-ee] FGA is configured but ${missingRoutes.length} protected route` +
      `${missingRoutes.length === 1 ? ' is' : 's are'} missing FGA metadata: ${routeList.join(', ')}`;

    if (auditMode === 'error') {
      throw new Error(message);
    }

    this.mastra.getLogger()?.warn(message, {
      routes: routeList,
      count: missingRoutes.length,
    });
  }

  /**
   * Register user-provided middleware from the Mastra config (`server.middleware`)
   * and from `mastra.setServerMiddleware()`. Called by init() between
   * registerAuthMiddleware() and registerHttpLoggingMiddleware().
   *
   * Mastra middleware handlers use Hono's `(c, next)` signature, so only
   * Hono-based adapters can run them. Those adapters override this method and
   * MUST wrap each handler with `skipIfFrameworkPublic` (exported by
   * `@mastra/hono`) so user middleware cannot block framework-public routes.
   * The default implementation warns when middleware is configured so the

View on GitHub (pinned to 75dd419e61)

Solutions

1. Add the required FGA metadata (relation/resource) to each route listed in the error message
2. Set auditMode to 'warn' or 'log' if you intentionally want to run without full FGA coverage while migrating
3. Exclude routes from protection (e.g. mark them public/internal) if they should not require FGA checks
4. Ensure route definitions are created via the auth-ee helpers that attach FGA metadata automatically instead of plain route objects

Example fix

// before
registerApiRoute('/agents', { method: 'GET', handler: ... })
// after
registerApiRoute('/agents', { method: 'GET', handler: ..., metadata: { fga: { relation: 'view', resource: 'agent' } } })

const missing = protectedRoutes.filter(r => !r.metadata?.fga);
if (missing.length) console.warn('Add FGA metadata to:', missing.map(r => r.path));

const hasFga = (r: { metadata?: Record<string, unknown> }): boolean =>
  r.metadata != null && 'fga' in r.metadata;

try {
  await mastraServer.start();
} catch (e) {
  if (e instanceof Error && e.message.includes('missing FGA metadata')) {
    console.error(e.message); // add metadata or downgrade auditMode
  } else throw e;
}

When it happens

Trigger: Configuring FGA auth (e.g. new MastraAuth<FgaConfig> with auditMode 'error') while registering custom routes wrapped with route protection that have no FGA metadata (relation/resource mapping), then starting the Mastra server.

Common situations: Upgrading auth-ee to a version that enforces FGA metadata on previously unprotected routes; adding custom API routes or server middleware that inherit protection but were never annotated with FGA relation metadata; forgetting metadata after copying route definitions from a non-FGA setup.

Related errors

• Clerk JWKS URI, secret key and publishable key are required,
• Cookie password must be at least 32 characters for SSO. Set
• Redirect URI is required for SSO login
• Google service account private key signing failed (${(err as
• Neon Auth base URL is required, please provide it in the opt

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