Open Source API Gateway

502 Bad Gateway: Upstream Proxy Rejected CONNECT

Membrane API Gateway returns 502 Bad Gateway when it forwards an HTTP CONNECT request to an upstream proxy that rejects the tunnel. Membrane closes the connection to that proxy. The cause is the upstream proxy or its configuration in Membrane.

The Error Response

The response contains the status 502 Bad Gateway, the problem type https://membrane-api.io/problems/gateway and the field proxy-status, which holds the status code returned by the upstream proxy. The type gateway means that the problem lies between Membrane and an upstream system, not in the client's request.

For this error, Membrane always suppresses the details, even in development mode. The response does not contain a link to this page or the internal detail Could not connect to proxy server, and its title is most likely the generic Internal Server Error. The proxy-status field is your main clue.

When Membrane Sends CONNECT to Another Proxy

Clients send CONNECT to tunnel HTTPS through Membrane running as a forward proxy. If an upstream proxy is configured in the HTTP client configuration, Membrane forwards the CONNECT to it. Any status above 299 from the upstream proxy leads to this error.

Note the two different proxies: the top-level proxy receives the client's CONNECT, while configuration.httpClientConfig.proxy is the upstream proxy that Membrane itself uses.

Common Causes

The Upstream Proxy Requires Authentication

The proxy-status is 407. Proxy authentication is not enabled, or the credentials are wrong.

The Upstream Proxy Does Not Allow the Tunnel

The policy of the upstream proxy does not allow tunnels to the requested host or port. The proxy-status is usually 403.

The Upstream Proxy Cannot Reach the Destination

The upstream proxy cannot connect to the requested destination and answers with its own 5xx error.

How to Fix It

  1. Read the proxy-status field of the response.
  2. If it is 407, enable proxy authentication:
configuration:
  httpClientConfig:
    proxy:
      host: proxy.example.com
      port: 3128
      authentication: true
      username: gateway
      password: secret
configuration:
  httpClientConfig:
    proxy:
      host: proxy.example.com
      port: 3128
      authentication: true
      username: gateway
      password: secret

Otherwise, check the access rules and the log of the upstream proxy for the destination the client tried to reach.

No Details in Any Mode

Unlike most Membrane errors, this one never contains the detail or the link to this page, not even in development mode. The proxy-status field is sent in every mode. To see more, check the log of the upstream proxy.

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.