Why does Membrane API Gateway return 502 Bad Gateway because of invalid framing?

The backend sent a response with invalid HTTP framing or a malformed header block, for example conflicting Content-Length values. Membrane cannot forward such a response safely and answers with 502 Bad Gateway.

How do I fix an invalid framing error in Membrane?

Fix the backend, or the component in front of it, so that it sends exactly one valid Content-Length and well-formed header lines. The gateway log names the backend URL and the exact 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 from error responses.

502 Bad Gateway: Invalid Response Framing

Membrane API Gateway returns 502 Bad Gateway when the backend's response has invalid HTTP framing or a malformed header block. Membrane cannot tell where the response ends, or cannot parse its headers, so it does not forward the response. The backend is at fault, not the client.

The Error Response

The response contains the status 502 Bad Gateway, the title Bad Gateway, a detail that repeats the message of the HTTP parser, the problem type https://membrane-api.io/problems/gateway and a link to this page. The type gateway means that the problem lies between Membrane and an upstream system, not in the client's request.

Why Framing Matters

The headers of an HTTP message tell the receiver how long the body is. If this information is ambiguous, two systems can disagree about where one message ends and the next begins. This is the basis of request and response smuggling attacks. Following RFC 9112, Membrane rejects such responses instead of guessing.

Common Causes

Conflicting Content-Length Values

The response contains several Content-Length values that disagree, either as separate header fields or as a comma-separated list.

An Invalid Content-Length Value

A Content-Length value is not a non-negative integer, or it is too large to represent.

A Header Line Without a Field Name

A header line has no field name followed by a colon, for example an obsolete folded continuation line that starts with whitespace.

Invalid Characters in a Field Name

A header field name contains a character that is not allowed, such as a control character. Whitespace between the field name and the colon is removed from responses, not rejected.

How to Fix It

Check the gateway log. Membrane logs the backend URL and the exact framing problem at warn level.
Capture the raw backend response, for example with curl -v or a network trace, to see the offending header.
Fix the backend, or the component in front of it such as another proxy, a framework or custom server code, so that it sends exactly one valid Content-Length and well-formed header lines.

Hide Details in Production

By default, Membrane runs in development mode and adds details to error responses that help you find the problem, including the link to this page. 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 ---.

In production mode, the title of this error is replaced by Internal Server Error, and the response only says Internal details are hidden. See server log (key: ...). Search the gateway log for that key to find the full error message.