mastra-ai/mastra · error · HTTPException

RBAC provider does not support role permission resolution

Error message

RBAC provider does not support role permission resolution

What it means

Thrown as a 404 by the GET /auth/roles/:roleId/permissions handler when the resolved RBAC provider exists but does not expose getPermissionsForRole. It means the configured RBAC backend cannot resolve per-role permission sets, regardless of who is calling.

Source

Thrown at packages/server/src/server/handlers/auth.ts:804

  responseSchema: rolePermissionsResponseSchema,
  summary: 'Get permissions for a role',
  description:
    'Returns the resolved permissions for a specific role. Only accessible by admin users. Used by the "View as role" feature.',
  tags: ['Auth'],
  handler: async ctx => {
    try {
      const { mastra, requestContext, roleId } = ctx as any;

      // Check that the caller is an admin
      const callerPermissions: string[] = requestContext?.get(MASTRA_USER_PERMISSIONS_KEY) ?? [];
      const isAdmin = callerPermissions.some((p: string) => p === '*' || p === '*:*');
      if (!isAdmin) {
        throw new HTTPException(403, { message: 'Admin access required' });
      }

      const rbac = getRBACProvider(mastra);
      if (!rbac?.getPermissionsForRole) {
        throw new HTTPException(404, { message: 'RBAC provider does not support role permission resolution' });
      }

      const permissions = await rbac.getPermissionsForRole(roleId);
      return { roleId, permissions };
    } catch (error) {
      if (error instanceof HTTPException) throw error;
      return handleError(error, 'Error getting role permissions');
    }
  },
});

// ============================================================================
// GET /auth/permission-patterns
// ============================================================================

export const GET_PERMISSION_PATTERNS_ROUTE = createRoute({
  method: 'GET',
  path: '/auth/permission-patterns',

View on GitHub (pinned to 75dd419e61)

Solutions

Implement getPermissionsForRole(roleId) on your RBAC provider, returning the permission list for a role.
Upgrade or replace the RBAC provider with one that supports role permission resolution.
If the backend cannot support it, stop calling this endpoint and maintain role-permission mappings on the client/admin side.
Check the Mastra version changelog for RBAC interface additions and update your custom provider accordingly.

Example fix

// before
class MyRbacProvider {
  async checkPermission() { /* ... */ }
}

// after
class MyRbacProvider {
  async checkPermission() { /* ... */ }
  async getPermissionsForRole(roleId: string): Promise<string[]> {
    return this.store.permissionsForRole(roleId);
  }
}

Defensive patterns

Strategy: type-guard

Validate before calling

// Server-side: before registering routes, assert RBAC capability
const rbac = getRBACProvider(mastra);
if (!rbac?.getPermissionsForRole) {
  console.warn('RBAC provider lacks getPermissionsForRole; role permission endpoint will 404');
}

Type guard

function supportsRolePermissionResolution(rbac: unknown): rbac is RBACProvider & { getPermissionsForRole: (roleId: string) => Promise<string[]> } {
  return typeof rbac === 'object' && rbac !== null && typeof (rbac as any).getPermissionsForRole === 'function';
}

Try / catch

try {
  const { permissions } = await getRolePermissions(roleId);
} catch (e) {
  if (e.status === 404 && /does not support role permission resolution/.test(e.message)) {
    throw new Error('Your RBAC provider cannot resolve role permissions — upgrade/implement getPermissionsForRole.');
  }
  throw e;
}

Prevention

Implement getPermissionsForRole on custom RBAC providers.
After upgrades, run an interface conformance check against the RBAC provider interface.
Feature-detect capability before exposing the role-permissions UI.
Keep custom providers in sync with the RBAC interface changelog.

When it happens

Trigger: Calling GET /auth/roles/:roleId/permissions on a server whose RBAC provider lacks a getPermissionsForRole method — e.g. a custom or legacy RBAC provider implementing only the base interface, or no full RBAC provider registered so a stub/partial provider is returned.

Common situations: Custom RBAC implementations built before getPermissionsForRole was added to the interface; running with a minimal/default RBAC setup and assuming role-permission introspection is available; version drift where the provider wasn't updated after upgrading Mastra.

Related errors

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