Why does the Membrane wsdl2openapi plugin return 500 Internal Server Error?

The plugin failed while translating between the JSON API it publishes and the SOAP service behind it. Either the JSON request could not be converted to SOAP, the SOAP response could not be converted to JSON, or the service answered a one-way operation with an error and no body.

How do I tell which case applies?

Read the detail of the response: The service did not carry out the operation, Could not transform SOAP response to JSON, or Could not transform JSON request to SOAP.

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: WSDL to OpenAPI Conversion Failed

Membrane API Gateway returns 500 Internal Server Error when the wsdl2openapi plugin fails while translating between the JSON API it publishes and the SOAP service behind it. Three different errors share this URL; the detail of the response says which one applies.

The Error Response

The response contains the status 500 Internal Server Error, one of the details listed below, 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 wsdl2openapi Plugin Does

The wsdl2openapi plugin reads a WSDL and publishes the SOAP service as a JSON API with an OpenAPI description. It converts JSON requests into SOAP messages and SOAP responses back into JSON. See WSDL to OpenAPI for an introduction. A SOAP fault from the service is reported separately as Operation failed.

Common Causes

Could Not Transform JSON Request to SOAP

The detail Could not transform JSON request to SOAP means the conversion failed in the request flow. Usually the client is at fault: the request body is not valid JSON, or it is not a JSON object although query or path parameters must be merged into it. The body can also be unreadable, or the request URI cannot be parsed.

The WSDL can also be the cause: the operation's input message has no parts, or its first part does not reference an element. The error message names the operation.

Could Not Transform SOAP Response to JSON

The detail Could not transform SOAP response to JSON means the conversion failed in the response flow. Usually the service is at fault: its response is not well-formed XML, for example an HTML error page, it has no SOAP Body, or the Body is empty. The body can also be unreadable, for example because of a wrong Content-Encoding.

The Service Did Not Carry Out the Operation

The detail The service did not carry out the operation means that the service answered a one-way operation, whose WSDL declares no output message, with a status outside 200 to 299 and an empty body. The status code is in the error message.

An Unexpected Exception in the Plugin

The same link also appears when the wsdl2openapi 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 wsdl2openapi 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

Client side: send a JSON object body that matches the published OpenAPI description.
SOAP service: return a well-formed SOAP envelope, or a SOAP fault on errors, instead of an empty or non-XML error response. A SOAP fault is passed on to the client as a problem document.
WSDL: use document/literal operations whose input message has a part that references an element.
Gateway operator: the exception is logged at error level together with the operation name. If the causes above do not explain it, report the problem with the stack trace on GitHub Issues.

A minimal API that publishes a SOAP service as JSON:

api:
  port: 2000
  flow:
    - wsdl2openapi:
        wsdl: partner.wsdl

api:
  port: 2000
  flow:
    - wsdl2openapi:
        wsdl: partner.wsdl

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.