500 Internal Server Error: OAuth2 Consent or Flow Start Failed

Membrane API Gateway uses this page for a 500 Internal Server Error of its OAuth2 authorization server (oauth2authserver) that occurs when the server fails to handle a request to its base path (/ or /?...) from a logged-in user. In this step, the server shows the consent page or starts the code, token or id_token token flow.

The Error Response

The client receives a bare 500 Internal Server Error with the title Internal Server Error and the problem type https://membrane-api.io/problems/internal. The type internal means that the gateway could not complete the processing of the request. For this error, Membrane always behaves as in production mode: the response contains no details and no link to this page, regardless of the gateway's configuration. The cause can only be found in the gateway log.

What Happens on the Base Path

An OAuth2 client sends the user to the authorization endpoint (<basePath>/oauth2/auth). The authorization server stores this pending authorization request, including the response_type, scopes and claims, in the user's session and lets the user log in. After the login, the user is sent to the base path, where the server asks for consent and continues the requested flow using the stored request.

Common Causes

The causes below are derived from how the server works and have not all been reproduced. Treat them as likely explanations, not as certainties.

No Pending Authorization Request in the Session

The session is logged in but holds no pending authorization request, because the user logged in through the login dialog directly instead of arriving from the authorization endpoint. The stored response_type is then missing, and choosing the flow fails with an internal error.

Unusual Scope or Claim Data

The pending authorization request holds scope or claim data that the consent page or the selected flow cannot process.

Another Exception in the Consent or Flow Handling

Any other exception while showing the consent page or starting the flow ends up here. Membrane logs it at error level with the stack trace. If the request is well-formed, this usually indicates a bug in Membrane.

How to Fix It

1. Client: start the login at the authorization endpoint (<basePath>/oauth2/auth, which an OAuth2 client calls), not by opening the login page or the server's base path directly.
2. Client: clear the session cookie and start the login again.
3. Operator: look for the stack trace in the Membrane log.
4. If the log does not point to a malformed request, report the stack trace on GitHub Issues.

For a working setup of the authorization server and a client, see the authorization code flow tutorial.

Details in Production Mode

Unlike most other errors, this one never includes details, the exception message or a link to this page in the response, not even in development mode. You do not need to configure anything to hide them. To analyze the error, use the gateway log.

Related Documentation

Configuration reference:

• oauth2authserver

Tutorials with runnable examples:

• OAuth2 Basics
• OAuth2 Client Credentials
• OAuth2 Password Flow

← All Membrane error messages