Skip to content

Federated Role Not Found

URI: https://docs.ankatech.co/errors/federated-role-not-found
HTTP Status: 422 Unprocessable Entity

When you see this

A federated login was refused because an admission rule or group-to-role mapping names a role the login path cannot resolve for the tenant. Resolution runs a two-step lookup — the tenant's own roles, then the global system catalogue — and this refusal means neither step returned a row.

Common Causes

  • The role name is misspelled, or the role was deleted after the rule or mapping was declared.
  • The rule names a custom role owned by a different tenant, which this tenant's lookup cannot see at all.

Response Example

{
  "type": "https://docs.ankatech.co/errors/federated-role-not-found",
  "title": "Federated Role Not Found",
  "status": 422,
  "detail": "Role not found: TENANT_KEY_CUSTODIAN",
  "instance": "/api/v3/admin/s2s/auth/idp/provision",
  "timestamp": 1730000000,
  "extensions": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Content-Type: application/problem+json — the response follows RFC 9457 Problem Details.

Both causes collapse into one type with one detail, which is a pure function of the submitted name. The collapse is structural — the lookup pair cannot see another tenant's custom role — so an absent role and a foreign one are indistinguishable by construction. This refusal reaches an unauthenticated browser, and separating them would turn the login surface into a cross-tenant catalogue oracle.

The type is deliberately not the generic not-found. A missing tenant on the same operation still raises that one, because it is an internal contract failure and must keep rendering as a platform defect rather than as a configuration problem.

How to Resolve

  1. Check the role name in the admission rule or group-to-role mapping against the tenant's role catalogue.
  2. If the role is a custom one, confirm it is owned by this tenant — a custom role from another tenant is never resolvable here.
  3. Create the role in this tenant, or point the rule at a system role that exists.

For full schema definitions, examples, and interactive testing, see the Developer Hub Reference.