Why does Membrane return 500 Groovy error during template rendering?

An expression in the template of the template plugin raised a Groovy runtime error, typically a MissingPropertyException for an unknown variable. This mostly happens with XML templates loaded from a location ending in .xml.

How do I find the failing expression in a Membrane template?

Read the exception message in the response in development mode or the log line Groovy error executing template. It names the missing property or method.

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: Groovy Error During Template Rendering

Membrane API Gateway returns 500 Internal Server Error with the detail Groovy error during template rendering. when an expression in the template of the template plugin raises a Groovy runtime error. The template belongs to the gateway configuration. This error mostly occurs with XML templates.

The Error Response

The response contains the status 500 Internal Server Error, the title Internal server error., the detail Groovy error during template rendering., 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. The plugin can fail in the request or the response flow. In both cases the client receives 500. In production mode, the title is replaced by Internal Server Error and the details are left out.

How the Template Plugin Reports Errors

The template plugin renders a Groovy template from src or location into the message body. For text and JSON templates, most errors are reported with the line of the template, see template expression failed. XML templates, whose location ends in .xml, are rendered differently, and their Groovy errors are reported with this page. Errors in text and JSON templates that cannot be mapped to a template line end up here as well.

Common Causes

An XML Template Uses a Missing Variable

A MissingPropertyException occurs for a typo in a variable name, for json… when the body is not valid JSON, or for params in the response flow or when the query string could not be parsed.

A Method Is Missing or Another Groovy Error Occurs

The template calls a method that does not exist on the object (MissingMethodException), or another Groovy runtime error occurs in one of its expressions.

How to Fix It

Read the exception message in the response (development mode) or in the log line Groovy error executing template: …. It names the missing property or method.
Correct the template, or guard the expression with the null-safe operator ?. or the Elvis operator ?:.
If the template expects JSON from the client, validate the body before template, for example with an OpenAPI document, so that invalid input is rejected with a 400.

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.