Why does the Membrane OAuth2 userinfo endpoint return 500 Internal Server Error?

The userinfo endpoint of the oauth2authserver plugin threw an unexpected exception while handling a request. Usually the request contains parameters that cannot be parsed, or the request cannot be read.

Why does the response not contain any details?

The userinfo endpoint always hides the details, even in development mode. The full error and the stack trace are written to the Membrane log at error level.

Does a missing or invalid access token lead to this error?

No. A missing, malformed or unknown access token gets a 400 or 401 response with a WWW-Authenticate error, not a 500.

500 Internal Server Error: OAuth2 Userinfo Endpoint Failure

Membrane API Gateway returns 500 Internal Server Error from the userinfo endpoint of the oauth2authserver plugin when that endpoint throws an unexpected exception while it handles a request.

The Error Response

The response contains the status 500 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 message. The endpoint always hides the details, so the title reads Internal Server Error, and the response contains neither an error message nor a link to this page, even in development mode. You find the link to this page in the gateway log.

What the Userinfo Endpoint Does

Clients call <basePath>/oauth2/userinfo with an access token and get the claims of the logged-in user as JSON. A missing, malformed or unknown access token does not lead to this 500: it gets a 400 or 401 with a WWW-Authenticate error.

Common Causes

A Parameter Is Sent Twice or Badly Encoded

The endpoint parses the query string and the form body strictly, as the token endpoint does. A repeated parameter or a malformed percent-escape makes parsing fail.

The Request Cannot Be Read

The request URI cannot be parsed, or the request body cannot be read or decoded.

The Token Can No Longer Be Resolved

The session still knows the access token, but the token generator can no longer resolve it. This can presumably happen when the token is revoked while the request is running. This cause has not been reproduced, so treat it as one possibility among others.

Writing the Claims Failed

Writing the user's claims as JSON failed. This indicates a bug in Membrane.

How to Fix It

Client side: send the token in the Authorization: Bearer <token> header, without repeated or badly encoded parameters.
Gateway operator: check the gateway log. The full stack trace is logged at error level and shows which cause applies.
If the log shows none of the parameter errors, report the problem with the stack trace on GitHub Issues.

Details Only in the Log

The userinfo endpoint always answers as if the gateway were running in production mode. Setting or removing production: true in the configuration does not change this response: the client gets neither the details nor the link to this page. Membrane writes the full error, including the stack trace, to the gateway log at error level. That log entry is the place to start.