Why does Membrane return 500 Error handling OpenAPI overview?

The OpenAPI publisher failed while it served the overview under /api-docs or a single document at /api-docs/ . Usually an OpenAPI document lacks info.title or info.version, or a servers URL is not a valid URI.

How do I fix Error handling OpenAPI overview in Membrane?

Make sure every published OpenAPI document has an info section with title and version and valid servers URLs, and check the rewrite settings of the openapi spec.

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. The response then only contains a log key that you can look up in the gateway log.

500 Internal Server Error: Error Handling OpenAPI Overview

Membrane API Gateway returns 500 Internal Server Error with the detail Error handling OpenAPI overview! when the OpenAPI publisher fails while it serves the overview under /api-docs or a single document at /api-docs/<id>. An OpenAPI document with missing parts or an invalid server URL is the usual cause.

The Error Response

The response contains the status 500 Internal Server Error, the title Internal server error., the detail Error handling OpenAPI overview!, the problem type https://membrane-api.io/problems/internal and a link to this page. In development mode, the exception message is included as well. The type internal means that the gateway could not complete the processing of the exchange. In production mode, the title is replaced by Internal Server Error and the details are left out.

What the OpenAPI Publisher Does

For an api with openapi specs, Membrane publishes the documents under /api-docs. The overview lists all documents as JSON, or as HTML when the Accept header contains html. A single document at /api-docs/<id> is returned with its server URLs rewritten to point to the gateway. See API docs publisher for details.

Common Causes

The Info Section Is Incomplete

An OpenAPI document has no info section, or info has no title or version. Building the JSON overview then fails. Every document needs at least:

openapi: 3.0.3
info:
  title: Fruit Shop API
  version: 1.0.0
servers:
  - url: https://api.predic8.de/shop/v2

openapi: 3.0.3
info:
  title: Fruit Shop API
  version: 1.0.0
servers:
  - url: https://api.predic8.de/shop/v2

A Server URL Is Not a Valid URI

A servers[].url in the document, or the value that the rewrite settings produce from it, is not a valid URI. Rewriting the document for /api-docs/<id> then fails.

The Request Has No Host Header

Rewriting the server URLs needs the Host header of the request. A client that sends none, which is possible with HTTP/1.0, causes this error for /api-docs/<id>.

The HTML Overview Could Not Be Rendered

An error occurred while Membrane rendered the HTML overview for a request with an Accept header containing html.

An Unexpected Exception in the Plugin

Any other exception that the openapiPublisher 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

Gateway operator: make sure every published OpenAPI document has info.title, info.version and valid servers[].url values.
Gateway operator: check the rewrite settings (host, port, protocol, basePath) of the openapi spec.
Client side: send a Host header.
Look at the exception in the response (development mode) or in the log. If the document and the request are fine, report it 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 instead of the details the response 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 and throws an unexpected exception, 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.