Open Source API Gateway

502 Bad Gateway: Unknown Backend Host

Membrane API Gateway returns 502 Bad Gateway when it cannot resolve the host name of the backend. The DNS lookup failed, so the request was not sent. The client is not at fault.

The Error Response

The response contains the status 502 Bad Gateway, a detail that names the host that could not be resolved, 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.

Common Causes

The Host Name Is Wrong

The host name in the target of the API is misspelled or does not exist:

api:
  port: 2000
  target:
    url: https://api.example.com
api:
  port: 2000
  target:
    url: https://api.example.com

DNS Does Not Resolve the Name from the Gateway

The name is valid, but not where Membrane runs. Internal names are often only known inside another network, a container network or a VPN.

A Proxy Is Needed but Not Configured

Some networks resolve external names only on an HTTP proxy. If no proxy is configured for Membrane, the lookup fails. Membrane logs a hint about this together with the error.

The Proxy Host Cannot Be Resolved

An outgoing proxy is configured, but its own host name cannot be resolved.

How to Fix It

  1. Check the host name in the detail field and correct the target of the API.
  2. Resolve the name on the gateway host with nslookup or dig, and fix the DNS configuration of that host or container.
  3. If outgoing traffic must use a proxy, configure it and check that the proxy host itself resolves:
configuration:
  httpClientConfig:
    proxy:
      host: proxy.example.com
      port: 3128
configuration:
  httpClientConfig:
    proxy:
      host: proxy.example.com
      port: 3128

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.

Related Documentation

Configuration reference:

Tutorials with runnable examples:

← All Membrane error messages

Still stuck? See the troubleshooting guide or ask on GitHub Issues. For commercial support, contact info@predic8.de.