Troubleshooting
When an agent invocation or a downstream OBO call is rejected, Catalyst returns a machine-readable code. Use the code to find the layer at fault and the fix. For the concepts behind these codes, see OAuth with the helper library and On behalf of.
Rejection codes
| Code | HTTP status | Meaning |
|---|---|---|
oauth.invalid_signature | 401 | The token's signature did not verify. |
oauth.invalid_issuer | 401 | The token's issuer is not in the trusted allowlist. |
oauth.expired | 401 | The token is past its expiry. |
oauth.missing_scope | 403 | The user authenticated but lacks a required scope. |
obo.exchange_failed | — | Catalyst could not mint the delegated token. |
obo.token_identity_absent | — | The token reached the server without the user's identity. |
Authentication codes (oauth.*)
These are returned to the caller when the inbound token fails verification or authorization.
oauth.invalid_signature
The signature on the presented JWT did not verify against the issuer's keys. Inspect the API logs to see which key set was used, and confirm the token was issued by the expected identity provider and not modified in transit.
oauth.invalid_issuer
The token's iss claim is not in the trusted allowlist for this deployment. Verify that a federation exists for that issuer and is delivered to the region serving the project. This is the most common failure when using a custom identity provider token, where the token comes from a provider that has not been federated.
oauth.expired
The token is past its expiry. For CLI callers, refresh credentials with diagrid login. For a custom identity provider token, re-acquire a fresh JWT from your provider's tooling.
oauth.missing_scope
The user authenticated but the token does not carry a scope your policy requires. Confirm the required scopes and check that the identity provider issues them for this user — scope conventions per provider are covered in IdP federation.
On-behalf-of codes (obo.*)
These surface in the API logs, not to the calling agent, and relate to propagating the user identity downstream.
obo.exchange_failed
Catalyst's call to mint the delegated token failed, so the downstream MCP call did not carry a user token. Inspect the API logs for the mcp_obo.exchange_failed event and the underlying error. See On behalf of for the event sequence.
obo.token_identity_absent
The downstream call succeeded, but the token that reached the MCP server did not carry the user's identity. This is expected when the MCPServerAccessPolicy uses a non-identity-propagating auth mode (client_credentials_ref or secret_ref) — the audit lineage is still preserved, but the user identity is not in the token itself. To put the user's identity into the downstream token, the MCP server must be Catalyst-hosted, where the authentication mode will mint a SPIFFE JWT with sub=user. See What the downstream server sees.
