---
title: OIDC troubleshooting
description: Diagnose authorization, token exchange, refresh, and registration errors.
editUrl: true
head: []
template: doc
sidebar:
  order: 6
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

Identify the failed endpoint before changing client configuration. Save the HTTP status, protocol `error`, time, and request correlation information when available. Do not log authorization codes, JWTs, client secrets, IATs, RATs, or callback bodies.

## Authorization errors

After the provider validates the callback, authorization errors return to it with `error`, `error_description`, `state` when supplied, and `iss`. Before acting on that response, validate `state` and compare `iss` with the issuer saved for the request. Errors before callback validation return directly as JSON.

| Error | Check | Recovery |
|---|---|---|
| `invalid_client` | Correct `client_id`; application is active and OIDC is configured. | Correct the registration or enable the application through its authorized OWNER. |
| `invalid_request` | Exact registered `redirect_uri`, required fields, duplicate parameters, nonce, PKCE, and supported `prompt` combinations. | Correct the request and start a new authorization. |
| `unsupported_response_type` | The issuer does not support the requested response type. | Select a type listed in discovery and permitted by the client. |
| `access_denied` | Authorization or current account admission did not succeed. | Review the reported reason and application admission rules. Do not retry silently in a loop. |
| `unauthorized_client` | Response type and its required grants are enabled for this client. | Have the OWNER review the OIDC ReturnRule. |
| `invalid_scope` | Requested scopes are supported and permitted for the client. | Reduce scope or update the approved client configuration. |
| `login_required` | `prompt=none` has no eligible remembered login. | Start interactive authorization when the user is ready. |
| `consent_required` | Silent authorization needs user consent. | Start interactive authorization to collect consent. |
| `interaction_required` | Required account data needs browser interaction. | Let the user complete the interactive flow. |
| `invalid_request_object` | RS256 preference, selected public keys, JWT fields, signature, and time claims. | Correct the signed object and create a fresh request. |
| `invalid_request_uri` | Registered reference allowance, exact URI, HTTPS access, and document availability. | Correct the reference or use an inline signed object. |
| `server_error` | Temporary provider failure. | Let the user retry; do not cache the error response. |

For `form_post`, confirm that the callback accepts a cross-site form POST. If your correlation cookie is missing, check `SameSite=None; Secure`. Reject the callback if you cannot verify its transaction state.

## Token exchange and refresh

Send `/token` requests as `application/x-www-form-urlencoded`. Use one client authentication method. Preserve the exact callback URI and PKCE verifier from the authorization transaction.

| Error | Common causes | Recovery |
|---|---|---|
| `invalid_request` | Wrong content type, duplicate fields, or missing form values. | Correct the form; do not repeat credential fields across methods. |
| `invalid_client` | Wrong secret; mismatched assertion `iss`/`sub`/`aud`; expired or reused assertion; missing or unmatched RP `kid`. | Check the selected authentication and key source. Create a fresh assertion with a fresh `jti`. |
| `unauthorized_client` | The requested grant is disabled. | Have the OWNER review allowed grants. |
| `unsupported_grant_type` | The endpoint does not support the supplied grant. | Use `authorization_code` or `refresh_token` as appropriate. |
| `invalid_grant` | Expired, consumed, or mismatched code; wrong verifier; revoked refresh session; conflicting refresh scopes. | Start a fresh authorization. Do not keep replaying the same code or old refresh token. |
| `invalid_scope` | Refresh tries to restore a scope removed from the session. | Use a subset of the current granted scopes, or start a new authorization for broader consent. |

An authenticated code replay can revoke the corresponding session. Serialize refresh requests and store each returned replacement refresh token. A missing `refresh_token` after narrowing away `offline_access` is expected. A missing `id_token` after narrowing away `openid` is expected.

Refresh OIDC tokens at `/token`, not Session `/refresh`. See [refresh rules](/en-us/oidc/flow/#4-refresh).

## UserInfo and claim state

Send the access token through the Bearer header or the supported form field, using one transport. Query-string tokens and duplicate transports are rejected.

If the endpoint returns `invalid_token`, check expiry, issuer, client/session authority, and whether the token belongs to this OIDC flow. If an expected claim is absent, check its scope, application policy, and current user grant. An `openid`-only claim-state request returns an empty `claims` object.

An ID Token is not an access token for UserInfo. Access tokens use the application's Session JWKS; ID Tokens and signed UserInfo use the provider JWKS. See [token verification](/en-us/concepts/tokens-and-verification/).

## Registration errors

| Result | Check | Recovery |
|---|---|---|
| HTTP 400 `invalid_client_metadata` | Metadata types, supported algorithms, scopes/grants, RP public keys, and naming policy. | Correct the JSON; keep it within the IAT's allowance. |
| HTTP 400 `invalid_redirect_uri` | URI syntax, application type, approved host placement, and sector document. | Correct the redirects and host approval. |
| HTTP 401 `invalid_token` | IAT/RAT expiry, revocation, quota, and current organization authority. | Ask the OWNER to review or replace the appropriate credential. |
| HTTP 403 on registration read/delete | RAT belongs to a different client. | Use that client's RAT and returned `registration_client_uri`. |

If `POST /register` has an unknown network result, review created clients in With before repeating it. A new request can consume another quota unit.

## Ask for support

Include the endpoint, time with timezone, HTTP status, protocol error, and a request identifier if supplied. State the response type, authentication method, and step that failed. Redact secrets and personal data. Use [Sudomimus support](https://sudomimus.com/en-US/help-center/).

## Related

- [OIDC flow](/en-us/oidc/flow/)
- [IAT and RAT management](/en-us/oidc/registration-access/)
- [RP keys](/en-us/oidc/relying-party-keys/)