Why does Membrane return 500 XSLT transformation failed?

The transform plugin could not read a file during the XSLT transformation. Usually the stylesheet loads a file with document() that does not exist or has a wrong path.

How are relative paths in document() resolved?

Relative paths in document() are resolved against the location of the stylesheet.

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, such as the exception message and the link to the documentation, from error responses.

500 Internal Server Error: XSLT Transformation Failed

Membrane API Gateway returns 500 Internal Server Error with the title XSLT transformation failed when the transform plugin cannot read a file during the transformation, in the request or response flow.

The Error Response

The response contains the status 500 Internal Server Error, the title XSLT transformation failed, a detail with the error message of the file access, 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 Transform Plugin Does

The transform plugin applies the XSLT stylesheet configured in xslt to the XML body of a message. This page covers errors where the error message of a file access contains No such file. Malformed XML input and other transformation errors get other responses.

Common Causes

A File Loaded with document() Is Missing

The stylesheet loads a file at runtime with document(), and that file does not exist or the path is wrong.

A Referenced File Was Moved or Deleted

A file that the stylesheet references was deleted or moved after the gateway started.

Different Wording on Windows

This error is recognized by the text No such file, as in No such file or directory. On Windows, the message for a missing file is worded differently, so the same problem is presumably reported through a different, more general error response there.

An Unexpected Exception in the Plugin

The same link also appears when the transform plugin throws an exception that it does not turn into an error response itself. Membrane then aborts the exchange with 500 Internal Server Error, and the detail reads Aborting! Exception caused in xslt-transformer during … flow. with the request URI and the flow. Membrane logs every occurrence with the full stack trace. Unless the exception points to your configuration or to the message content, this usually indicates a bug in Membrane.

How to Fix It

Check the path in the detail, and make sure the file exists and is readable by the Membrane process.
Relative paths in document() are resolved against the location of the stylesheet.
Check the gateway log. The error is logged at error level together with the configured xslt.

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.

If the plugin is nested inside a request, response or abort element and fails with an unexpected exception there, 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.