Why does Membrane return 500 Could not parse OpenAPI with title ...?

The openapi validation could not check a request because the OpenAPI document is incomplete at the point the validation needed, usually because a $ref points to a schema under components.schemas that does not exist.

Is the request wrong when Membrane reports Could not parse OpenAPI?

No. The OpenAPI document in the gateway configuration is to blame. Fix the document and every request that uses the affected schema will be validated again.

How do I find the broken reference in my OpenAPI document?

Validate the document with an OpenAPI linter, and look at the exception in the response in development mode or in the gateway log.

500 Internal Server Error: Could Not Parse OpenAPI

Membrane API Gateway returns 500 Internal Server Error with the detail Could not parse OpenAPI with title … Check syntax and references. when it cannot validate a request because the OpenAPI document is incomplete. The OpenAPI document in the gateway configuration is to blame, not the request.

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 … Check syntax and references. with the title of your document, 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.

How Membrane Validates Requests Against OpenAPI

An api with openapi specs can validate requests against the document, see OpenAPI configuration and validation. While it validates, Membrane resolves the $ref references of the operation. If a reference points to nothing, the validation cannot continue and Membrane answers with this error in the request flow.

Common Causes

The Components Section Is Missing

The document uses $ref: '#/components/schemas/…' but has no components section, or components has no schemas.

A Form Field Refers to a Missing Schema

A property of an application/x-www-form-urlencoded request body refers with $ref to a schema that does not exist under #/components/schemas.

Another Reference Cannot Be Resolved

Another place where the validator needs a schema resolves to none. Every $ref must point to an existing entry:

paths:
  /products:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Product'
components:
  schemas:
    Product:
      type: object
      properties:
        name:
          type: string

paths:
  /products:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Product'
components:
  schemas:
    Product:
      type: object
      properties:
        name:
          type: string

How to Fix It

Validate the OpenAPI document with a linter and fix every unresolved $ref. Every referenced schema must exist under components.schemas.
Restart or reload the gateway after fixing the document, so that the openapi specs are read again.
Look at the exception in the response (development mode) or in the log to see which reference failed.

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.