Why does the Membrane template plugin return 500 with a rendering error?

The template plugin failed with an exception that is neither a Groovy error nor a failing template expression, for example a non-Groovy error in an XML template or an error while the rendered body was written to the message.

What should I do when a Membrane template fails to render?

Check the template and its contentType. If the template does not explain the error, get the stack trace from the response in development mode or from the log and report it on GitHub Issues.

500 Internal Server Error: Template Rendering Failed

Membrane API Gateway returns 500 Internal Server Error with a link to this page when the template plugin fails with an exception that is neither a Groovy error nor a failing template expression. This is rare.

The Error Response

The response contains the status 500 Internal Server Error, the title Internal server error., 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. Groovy errors and failing expressions have their own pages: Groovy error during template rendering and template expression failed. All other exceptions are reported with this page.

Common Causes

A Non-Groovy Error in an XML Template

An XML template, whose location ends in .xml, failed with an exception that is not a Groovy error.

The Rendered Body Could Not Be Written

An exception occurred while Membrane wrote the rendered body to the message.

How to Fix It

Check the template and its contentType.
If the template does not explain the error, get the stack trace from the response (development mode) or from the log, and report it 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.