Why does Membrane return 500 Could not resolve file?

A file that Membrane should return could not be resolved. This happens when the wsdlPublisher plugin loads the published WSDL or a schema it references and that file does not exist or cannot be read.

Why do I see a WSDL rewriting error instead?

The wsdlPublisher passes this error through the WSDL rewriter, which usually fails on it. Clients therefore mostly receive the internal/wsdl-rewriting error for the same underlying problem.

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 Resolve File

Membrane API Gateway reports 500 Internal Server Error with the title Could not resolve file when the web-server component cannot load a file it should return. This error is rare: the component is used this way only by the wsdlPublisher plugin, when it loads the published WSDL or a schema that the WSDL references.

The Error Response

The error contains the status 500 Internal Server Error, the title Could not resolve file, the problem type https://membrane-api.io/problems/internal and a link to this page. In development mode, the path field shows the file that could not be resolved. 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.

Clients often do not see this response directly. The wsdlPublisher labels the error document as XML and runs the WSDL rewriter over it, which then fails. The client therefore usually receives the WSDL rewriting error instead. The underlying problem is the same missing file.

Common Causes

The WSDL Cannot Be Found

The wsdl of the wsdlPublisher, or the WSDL of the enclosing soapProxy, points to a file or URL that does not exist or cannot be read at request time.

A Referenced Schema Cannot Be Found

A schema that the WSDL imports or includes through schemaLocation cannot be resolved.

An Unexpected Exception in the Plugin

The same link also appears when the webServer 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 web-server 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 wsdl location and every schemaLocation it references. Relative paths are resolved against the directory of the configuration file.
In development mode, the path field of the response shows the failing path.
For errors thrown by webServer, check the gateway log and report the problem with the stack trace on GitHub Issues.

A wsdlPublisher with a WSDL next to the apis.yaml looks like this:

api:
  port: 2000
  flow:
    - wsdlPublisher:
        wsdl: city-service.wsdl

api:
  port: 2000
  flow:
    - wsdlPublisher:
        wsdl: city-service.wsdl

All schema files that city-service.wsdl references must be available relative to the 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.