{"record":{"id":"feeda7ce3e621042","repo":"mastra-ai/mastra","slug":"mastra-auth-ee-fga-is-configured-but-missingro","errorCode":null,"errorMessage":"[mastra/auth-ee] FGA is configured but ${missingRoutes.length} protected route${missingRoutes.length === 1 ? ' is' : 's are'} missing FGA metadata: ${routeList.join(', ')}","messagePattern":"\\[mastra/auth-ee\\] FGA is configured but (.+?) protected route(.+?) missing FGA metadata: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/server/src/server/server-adapter/index.ts","lineNumber":937,"sourceCode":"      await fgaProvider.validatePermissions(permissions);\n    }\n\n    const auditMode = fgaProvider.auditProtectedRoutes ?? (fgaProvider.requireForProtectedRoutes ? 'warn' : false);\n    if (!auditMode || fgaProvider.resolveRouteFGA) return;\n\n    const missingRoutes = routes.filter(\n      route => isProtectedFGARoute(route) && !route.fga && !getBuiltInRouteFGAConfig(route),\n    );\n\n    if (missingRoutes.length === 0) return;\n\n    const routeList = missingRoutes.map(route => formatRoute(route as ServerRoute));\n    const message =\n      `[mastra/auth-ee] FGA is configured but ${missingRoutes.length} protected route` +\n      `${missingRoutes.length === 1 ? ' is' : 's are'} missing FGA metadata: ${routeList.join(', ')}`;\n\n    if (auditMode === 'error') {\n      throw new Error(message);\n    }\n\n    this.mastra.getLogger()?.warn(message, {\n      routes: routeList,\n      count: missingRoutes.length,\n    });\n  }\n\n  /**\n   * Register user-provided middleware from the Mastra config (`server.middleware`)\n   * and from `mastra.setServerMiddleware()`. Called by init() between\n   * registerAuthMiddleware() and registerHttpLoggingMiddleware().\n   *\n   * Mastra middleware handlers use Hono's `(c, next)` signature, so only\n   * Hono-based adapters can run them. Those adapters override this method and\n   * MUST wrap each handler with `skipIfFrameworkPublic` (exported by\n   * `@mastra/hono`) so user middleware cannot block framework-public routes.\n   * The default implementation warns when middleware is configured so the","sourceCodeStart":919,"sourceCodeEnd":955,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/server-adapter/index.ts#L919-L955","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add the required FGA metadata (relation/resource) to each route listed in the error message","Set auditMode to 'warn' or 'log' if you intentionally want to run without full FGA coverage while migrating","Exclude routes from protection (e.g. mark them public/internal) if they should not require FGA checks","Ensure route definitions are created via the auth-ee helpers that attach FGA metadata automatically instead of plain route objects"],"exampleFix":"// before\nregisterApiRoute('/agents', { method: 'GET', handler: ... })\n// after\nregisterApiRoute('/agents', { method: 'GET', handler: ..., metadata: { fga: { relation: 'view', resource: 'agent' } } })","handlingStrategy":"validation","validationCode":"const missing = protectedRoutes.filter(r => !r.metadata?.fga);\nif (missing.length) console.warn('Add FGA metadata to:', missing.map(r => r.path));","typeGuard":"const hasFga = (r: { metadata?: Record<string, unknown> }): boolean =>\n  r.metadata != null && 'fga' in r.metadata;","tryCatchPattern":"try {\n  await mastraServer.start();\n} catch (e) {\n  if (e instanceof Error && e.message.includes('missing FGA metadata')) {\n    console.error(e.message); // add metadata or downgrade auditMode\n  } else throw e;\n}","preventionTips":["Use a route helper that always attaches FGA metadata","Run an audit-mode startup in CI as a check","Keep a list of intentionally unprotected routes and exclude them explicitly"],"tags":["auth","fga","routes","configuration"],"backgroundTag":"fga-route-metadata-missing","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}