Skip to content

Role Catalog Flush Not Published

URI: https://docs.ankatech.co/errors/role-catalog-flush-withheld
HTTP Status: 503 Service Unavailable

When you see this

You asked admin-api to flush the role catalog, the operation that tells every service to drop its role-to-scope cache, but the flush could not be signed or sent. No service dropped its cache: each one still serves the role scopes it cached, and they expire on their own L1 timer (60 s by default).

admin-api signs every role-scope invalidation before it publishes it, so a reader can trust it. When it cannot sign or send the flush, it refuses rather than reporting a flush that did not happen. The refusal is audited as a failed flush.

extensions.reason names the cause:

reason Cause
signer-refused Once the installed release is finalized, invalidations are signed with the projection signing key set, and this replica holds no current key. Readiness reports projectionSigningKeys DOWN.
secret-absent Before finalize, invalidations are signed with role_scope_signing_secret, and that secret is not mounted. Readiness reports roleScopeReadiness DOWN.
publish-failed The signed flush could not be serialized or published to Redis.

Response Example

{
  "type": "https://docs.ankatech.co/errors/role-catalog-flush-withheld",
  "title": "Role Catalog Flush Not Published",
  "status": 503,
  "detail": "The role-catalog flush could not be signed or published, so no service dropped its role-scope cache. Retry once the cause named in reason is resolved.",
  "instance": "/api/v3/admin/platform/cache/role-catalog/flush",
  "extensions": {
    "reason": "signer-refused",
    "requestId": "3f7c2a91-6d4e-4b8a-9c15-0e2d8b7a4f63"
  }
}

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

Extension Meaning
reason signer-refused, secret-absent or publish-failed, as in the table above
requestId The request's correlation identifier

detail is fixed text. Read the cause from extensions.reason, never from detail.

How to Resolve

  1. Read extensions.reason.
  2. signer-refused: check System Health for projectionSigningKeys on admin-api. A replica that cannot re-read the projection signing key set stops signing; restore its custody access, and the key is read again within one refresh.
  3. secret-absent: provide the role-scope signing secret to admin-api, as the deployment's secrets reference describes, and restart it.
  4. publish-failed: check Redis (Valkey) reachability from admin-api.
  5. Retry the flush. Until a flush succeeds, a role change reaches every reader within its L1 timer.

Operations that emit it

Method Endpoint
POST /api/v3/admin/platform/cache/role-catalog/flush
  • Platform alerts* — the rbac.role-scope.invalidation.withheld condition counts invalidations withheld after a role change.
  • Service Unavailable — the generic 503.

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

* restricted content — see higher-tier documentation