Why does Membrane API Gateway return 500 Could not parse OpenAPI during response validation?

Response validation is on, but the OpenAPI document cannot be used to validate the backend response. Usually a $ref in a response definition points to an entry under components/schemas that does not exist.

How do I fix the OpenAPI parsing error in Membrane?

Fix the OpenAPI document so that every $ref points to an existing schema under components/schemas, then reload the gateway. The log contains the exception. As a temporary workaround, set validateResponses: false on the openapi entry.

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: OpenAPI Document Cannot Validate the Response

Membrane API Gateway returns 500 Internal Server Error when response validation is on, but the OpenAPI document cannot be used to validate the backend response. Parts of the document that its references point to are missing. The cause is the OpenAPI document in the gateway configuration, not the client or the backend.

The Error Response

The response contains the status 500 Internal Server Error, the title Internal server error., the detail Could not parse OpenAPI with title Fruit Shop API. Check syntax and references. with the title of the 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 process the message. In production mode, the title is Internal Server Error and the detail is replaced by a log key.

How Response Validation Works

With validateResponses on, the OpenAPI validator checks every backend response against the response definitions of the operation in the OpenAPI document. To do that, it resolves the schemas the definitions refer to. If a referenced part is missing, the response cannot be validated, and the client receives this error instead of the backend response.

Common Causes

A $ref Points to Missing Components

A response definition refers to #/components/schemas/Product, but the document has no components section, no schemas section, or no schema with that name:

paths:
  /products:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'

paths:
  /products:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'

A Referenced Schema Cannot Be Resolved

The reference contains a typo, uses the wrong case, or points to a schema that was renamed or removed. The validator then has no schema to validate against.

How to Fix It

Look up the exception in the log. Membrane logs Could not parse OpenAPI with title ... at warn level. In production mode, search the log for the key from the response.
Fix the OpenAPI document so that every $ref points to an existing entry under components/schemas. A linter or editor with OpenAPI support finds broken references quickly.
Reload the gateway.

As a temporary workaround, switch off response validation for the document:

api:
  port: 2000
  openapi:
    - location: fruitshop-api.yml
      validateResponses: false

api:
  port: 2000
  openapi:
    - location: fruitshop-api.yml
      validateResponses: false

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 ---.