Why does Membrane return 500 Could not handle login request?

The login plugin failed while it handled a request to its login dialog, for example because a form parameter was sent twice, the consent parameter was missing, or the second-factor token could not be sent.

How do I fix a two-factor login that fails with 500 in Membrane?

Make sure every user has the attributes the token provider needs, for example a phone number for an SMS token provider, and that the mail or SMS gateway is reachable from the gateway.

How do I hide the details in Membrane error responses?

Enable production mode by adding a configuration document with production: true to your apis.yaml. The response then only contains a log key that you can look up in the gateway log.

500 Internal Server Error: Could Not Handle Login Request

Membrane API Gateway returns 500 Internal Server Error with the detail Could not handle login request.! when the login plugin fails while it handles a request to its login dialog. The client's input, the second-factor token provider or the login dialog configuration is usually to blame.

The Error Response

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

What the Login Plugin Does

The login plugin protects an API with a login form. Requests under its path are handled by the login dialog: the login form, the form for a second-factor token, the consent page, the logout and the static resources of the dialog, which are loaded from location. If handling one of these requests throws an exception, Membrane answers with this error.

Common Causes

A Form Parameter Is Repeated or Malformed

Membrane parses the query string and the form parameters of the dialog strictly. A parameter name that occurs more than once, or an invalid percent-escape such as %zz, is rejected with Could not parse query: ….

The Consent Parameter Is Missing

A POST to the consent page must contain the consent form parameter. A hand-built request without it fails.

The Second-Factor Token Could Not Be Sent

After a correct password, the configured token provider issues the second-factor token. This fails if the user has no attribute the provider needs, for example no sms attribute for an SMS token provider, or if sending the e-mail or SMS fails.

The Request or the Dialog Page Is Broken

The request URI cannot be parsed, the form body could not be read, or the login page template from location could not be rendered.

An Unexpected Exception in the Plugin

Any other exception that the login plugin does not turn into an error response itself is reported under the same URL by Membrane's generic error handler. The detail then reads Aborting! Exception caused in … flow. and names the plugin, the request URI and the flow. Unless the exception points to your configuration or to the message, this usually indicates a bug in Membrane.

How to Fix It

Client side: submit the login form as the dialog provides it, without repeated or hand-built parameters.
Gateway operator: for two-factor logins, make sure every user has the attributes the token provider needs, and that its mail or SMS gateway is reachable.
Gateway operator: check that the dialog templates under location are complete and valid.
Look at the exception in the response (development mode) or in the log. If it looks like an internal error, report it 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 instead of the details the response only contains a log key. Search the gateway log for this key to find the exception.

If the plugin is nested inside a request, response or abort element and throws an unexpected exception, the exception message, the stack trace and the link to this page are currently sent even in production mode. Fix the failing plugin rather than relying on production mode to hide them.