500 Internal Server Error: Error Handling Request in OAuth2 Resource

Membrane API Gateway returns 500 Internal Server Error with the detail Error handling request! when the OAuth2 client plugin oauth2Resource2 throws an unexpected exception while it handles a request.

The Error Response

The response contains the status 500 Internal Server Error, the detail Error handling request!, the problem type https://membrane-api.io/problems/internal and a link to this page. The type internal means that the gateway could not complete the processing of the message. In production mode, the title is replaced by Internal Server Error and the details are left out.

What the OAuth2 Resource Plugin Does

The oauth2Resource2 plugin protects an API with an OAuth2 or OpenID Connect login. It redirects unauthenticated users to the authorization server, handles the callback and keeps the login in a session. OAuth2 protocol errors are handled separately and do not end up here, so this error usually points to the gateway configuration or environment, or to a bug in Membrane. For the flow in general, see the authorization code flow tutorial.

Common Causes

A Query String Cannot Be Parsed

The query string of the callback, or of a redirect back from the login, cannot be parsed, for example because a parameter appears twice or has no =.

The Original Request Cannot Be Restored

Before the login redirect, the plugin stores the original request in the session. If that session entry is missing or corrupt, it cannot be read back.

The Login Redirect Cannot Be Built

The login URL of the authorization server, or the public URL of the gateway, cannot be determined.

The Session Store Failed

A remote session store, for example Redis or Memcached, failed while the session was read.

How to Fix It

1. Check the gateway log. The stack trace is logged at error level. In production, use the log key of the response to find it.
2. Check that the authorization server configured in oauth2Resource2 is reachable and returns a valid discovery document and login URL.
3. Check that the backend of the session manager is reachable.
4. If the client sends a clean request and the configuration is correct, report the problem with the stack trace on GitHub Issues.

Hide Details in Production

By default, Membrane runs in development mode and adds details to error responses that help you find the problem. These details may reveal information about your setup. In production, turn them off:

configuration:
  production: true

configuration:
  production: true

Add the configuration document to your apis.yaml and separate it from the APIs with ---. The title then reads Internal Server Error, and the details and the link to this page are left out. If the response contains a log key, search the gateway log for it to find the full error message.

Related Documentation

Configuration reference:

• oauth2Resource2

Tutorials with runnable examples:

• OAuth2 Basics

← All Membrane error messages