Why does Membrane API Gateway return 500 with Could not rewrite endpoint!?

The wsaEndpointRewriter plugin could not process the SOAP message body to rewrite its WS-Addressing ReplyTo address. The body is empty, not well-formed XML, contains a DOCTYPE, or the address is not a valid URI.

How do I fix the Could not rewrite endpoint! error in Membrane?

Make sure the client or backend sends well-formed SOAP messages without a DOCTYPE and with a valid URI as the ReplyTo address, and apply the plugin only to APIs that carry SOAP with WS-Addressing.

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: Could Not Rewrite Endpoint

Membrane API Gateway returns 500 Internal Server Error with the detail Could not rewrite endpoint! when the wsaEndpointRewriter plugin cannot process the body of a SOAP message. The cause is the message: the client's request or the backend's response.

The Error Response

The response contains the status 500 Internal Server Error, the detail Could not rewrite endpoint!, 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 WSA Endpoint Rewriter Does

The wsaEndpointRewriter plugin rewrites the WS-Addressing ReplyTo/Address of SOAP messages so that it points at the gateway instead of the original endpoint. The new address is built from the plugin's protocol, host and port. To do this, the plugin has to parse the whole message body as XML.

Common Causes

The Body Is Not Well-Formed XML

The body is empty, is not XML at all, or is not well-formed XML, for example because it was truncated.

The Body Contains a DOCTYPE

The plugin uses a hardened XML parser that rejects DOCTYPE declarations to protect against XML attacks. A message with a DOCTYPE cannot be rewritten.

The ReplyTo Address Is Invalid

The address inside ReplyTo/Address is not a valid URI, or the Address element contains child elements instead of plain text.

The Body Could Not Be Read

The body could not be read or decoded, for example because the connection was closed early or the Content-Encoding is invalid.

An Unexpected Exception in the Plugin

Any other exception that the wsaEndpointRewriter 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 or backend: send well-formed SOAP messages without a DOCTYPE and with a valid URI as the ReplyTo address.
Gateway operator: check the gateway log, which contains the full exception.
Apply the plugin only to APIs that carry SOAP with WS-Addressing.
If the message is valid, report the problem with the stack trace on GitHub Issues.

For SOAP in Membrane in general, see the SOAP tutorial.

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.