Why does Membrane return 500 Could not return WSDL document!?

The wsdlPublisher plugin threw an unexpected exception while answering a request for the WSDL or a referenced schema. Usually the query string cannot be parsed, for example because the xsd parameter appears twice.

How do I request the WSDL and its schemas from Membrane?

Request the WSDL with ?wsdl and a referenced schema with exactly one xsd parameter, such as ?xsd=1, as in the links of the published WSDL.

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: Could Not Return WSDL Document

Membrane API Gateway returns 500 Internal Server Error with the detail Could not return WSDL document! when the wsdlPublisher plugin fails unexpectedly while it answers a GET request for the WSDL (?wsdl) or for a referenced schema (?xsd=<n>).

The Error Response

The response contains the status 500 Internal Server Error, the detail Could not return WSDL document!, 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 WSDL Publisher Does

The wsdlPublisher plugin publishes a WSDL and the schemas it references, so that clients can download them from the gateway. It is also part of a soapProxy. Cases the plugin handles itself do not lead to this error: a non-numeric xsd value gets a 400, an unknown schema number a 403, and a missing document a 404.

Common Causes

A Query Parameter Is Sent Twice

The query string repeats a parameter, for example ?xsd=1&xsd=2. The plugin parses parameters strictly and rejects duplicates with Could not parse query.

A Malformed Query String or URI

The query string contains a malformed percent-escape, so URL decoding fails, or the request URI cannot be parsed at all.

An Unexpected Exception in the Plugin

The same link also appears when the wsdlPublisher 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 wsdl-publisher 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: request ?wsdl, or exactly one xsd parameter such as ?xsd=1, as the links in the published WSDL do.
Gateway operator: check the gateway log. The exception is logged at error level.
If the log shows none of the causes above, report the problem with the stack trace 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 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.