Why does Membrane API Gateway return 502 Bad Gateway when connecting to the backend?

Membrane could not open a TCP connection to the backend configured as the target of the API. The connection was refused or could not be established, so the request never reached the backend.

How do I fix a 502 connect error in Membrane?

Check that the backend is running and reachable from the gateway host, correct the target url of the API, and configure an outgoing HTTP proxy if the backend is only reachable through one.

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: Could Not Connect to Backend

Membrane API Gateway returns 502 Bad Gateway when it cannot open a connection to the backend of an API. The connection was refused or could not be established, so the request was never sent. The client is not at fault.

The Error Response

The response contains the status 502 Bad Gateway, the title Bad Gateway, a detail that names the destination Membrane tried to reach, 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.

How Membrane Forwards Requests

After the plugins of the flow have run, the HTTP client of Membrane forwards the request to the target of the API. To do this, it opens a TCP connection to the host and port of the target. If that fails, Membrane answers with this error.

Common Causes

The Backend Is Not Running

Nothing listens on the target host and port. The backend is down, has not started yet, or listens on a different port.

The Target Points to the Wrong Host or Port

Check the url (or host and port) of the target:

api:
  port: 2000
  target:
    url: http://backend.example.com:8080

api:
  port: 2000
  target:
    url: http://backend.example.com:8080

A Firewall Rejects the Connection

A firewall, security group or container network actively rejects connections from the gateway host to the backend.

The Backend Is Only Reachable Through a Proxy

If outgoing traffic has to pass an HTTP proxy and no proxy is configured, the direct connection fails. Membrane logs a hint about this together with the error. Configure the proxy for the HTTP client:

configuration:
  httpClientConfig:
    proxy:
      host: proxy.example.com
      port: 3128

configuration:
  httpClientConfig:
    proxy:
      host: proxy.example.com
      port: 3128

All Retries Failed

When failover or retries are configured, this error means that every attempt failed. The detail names only the first destination.

How to Fix It

Take the destination from the detail field and call it from the gateway host, for example with curl.
Start the backend, or correct the target of the API if it points to the wrong host or port.
Open the firewall for connections from the gateway, or configure an outgoing proxy.

To ride out short backend restarts, tune the retry behavior of the HTTP client:

configuration:
  httpClientConfig:
    retries:
      retries: 5
      delay: 500

configuration:
  httpClientConfig:
    retries:
      retries: 5
      delay: 500

Clients can safely retry later, because the request never reached the backend.

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.