Why does the if plugin of Membrane API Gateway return 500?

The if plugin could not evaluate its test expression against the current request or response. Usually the expression is wrong, for example a missing method or an invalid JSONPath or XPath, sometimes the message body is not valid JSON or XML.

Is a test expression that evaluates to null an error?

No. An expression that evaluates to null counts as false, and the else branch runs if there is one.

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. Membrane then leaves out detailed information from error responses.

500 Internal Server Error: If Condition Failed

Membrane API Gateway returns 500 Internal Server Error when the if plugin cannot evaluate its test expression against the current request or response. The fault is usually in the gateway configuration, sometimes in a message body that is not valid JSON or XML.

The Error Response

The response contains the status 500 Internal Server Error, a detail that describes the evaluation problem, 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. The error can occur in the request and in the response flow; in both cases the client receives a 500. In production mode, the title is replaced by Internal Server Error and the details are left out.

What the If Plugin Does

The if plugin evaluates the condition in test and runs its nested flow when the result is true, or the else flow otherwise. The expression language is set with language: spel, jsonpath, xpath or groovy. An expression that evaluates to null is not an error; it counts as false.

api:
  port: 2000
  flow:
    - if:
        test: request.headers['X-Beta-User'] == 'true'
        flow:
          - destination:
              url: https://api.v2.example.com/user
  target:
    url: https://api.v1.example.com/user

api:
  port: 2000
  flow:
    - if:
        test: request.headers['X-Beta-User'] == 'true'
        flow:
          - destination:
              url: https://api.v2.example.com/user
  target:
    url: https://api.v1.example.com/user

See scripting with Groovy, JavaScript and SpEL for the expression languages.

Common Causes

The SpEL Expression Fails

The expression refers to a method that does not exist, fails at runtime (for example a property access on a null value), or yields a value that cannot be converted to a boolean. The detail names the problem. If a Membrane built-in function fails, it is named in the function field of the response.

The JSONPath Is Invalid or the Body Is Not JSON

With language: jsonpath, the path is syntactically invalid, or the body cannot be read as the expected JSON.

The XPath Is Invalid or the Body Is Not XML

With language: xpath, the expression is invalid, uses a namespace prefix that is not declared, or the body has characters before the XML declaration or after the root element.

An Unexpected Exception in the Plugin

Any other exception thrown by the plugin, including a runtime error in a groovy test, 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. An exception in a plugin nested inside the if is reported under the URL of that nested plugin, not under this one.

How to Fix It

Operator: check the test expression and its language against the message the plugin receives in the flow where it is placed.
Operator: for XPath with prefixes, declare the namespaces in the xmlConfig of the if or of the enclosing API.
Client: when the detail shows a body parsing problem, send a well-formed JSON or XML body.
Enable development mode to see the expression and the error in the response. In production, look up the log key of the response in the gateway log.

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 response then 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, 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.