Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

nginx reverse proxy to an HTTPS backend fails the SSL handshake

Error502 Bad Gateway when proxy_pass uses https://

Short answer

When proxy_pass points at https://, nginx does not send the server name during the TLS handshake unless you turn that on. Hosts that serve many sites from one address then reject or misroute the connection. Set proxy_ssl_server_name on, keep Host at its default, and check verification settings.

  • Applies to nginx 1.26, OpenSSL 3.0, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Open a TLS connection to the backend yourself, once without and once with the server name, and compare. If only the second works, nginx needs SNI.

    openssl s_client -connect backend.example.net:443 -brief </dev/null
    openssl s_client -connect backend.example.net:443 -servername backend.example.net -brief </dev/null
  2. 2Match what you see, then jump to its fix

    1. 1The first s_client run fails or returns a default certificate, and the second works.nginx does not send the server name (SNI) to the backendFix
    2. 2The handshake works, but the backend answers with its own error page or a different site.The Host header is your own domain, not the backend'sFix
    3. 3The handshake fails only after you added proxy_ssl_verify on.Certificate verification is on but nginx has no CA fileFix

What does the error look like?

  • 502 Bad Gateway when proxy_pass uses https://
  • SSL handshake failure on the connection from nginx to the upstream

Cause 1 of 3

nginx does not send the server name (SNI) to the backend

1Check

proxy_ssl_server_name is off by default, so no server name is passed to the proxied HTTPS server.

grep -R -n -E "proxy_pass|proxy_ssl_server_name" /etc/nginx/

2Fix

Turn on SNI for that location. The name sent is the host part of the proxy_pass URL unless you override it with proxy_ssl_name.

location / {
    proxy_pass https://backend.example.net;
    proxy_ssl_server_name on;
}

3Verify

Reload and request through nginx.

sudo nginx -t && sudo systemctl reload nginx
curl -I https://example.com

Confirmed by nginx.org

Did this fix it?

Cause 2 of 3

The Host header is your own domain, not the backend's

1Check

By default nginx sends the Host value of the proxy_pass target. A line such as proxy_set_header Host $host replaces it with the name visitors typed.

grep -R -n "proxy_set_header Host" /etc/nginx/

2Fix

Remove the override, or set it explicitly to the backend's name, when the backend picks the site by hostname.

proxy_set_header Host $proxy_host;

3Verify

Request a page through nginx and compare with the backend directly.

curl -I https://example.com
curl -I https://backend.example.net

Confirmed by nginx.org

Did this fix it?

Cause 3 of 3

Certificate verification is on but nginx has no CA file

1Check

proxy_ssl_verify is off by default. Turned on, it needs proxy_ssl_trusted_certificate with the CA certificates in PEM, and the certificate must match the name nginx uses (proxy_ssl_name, by default the host in proxy_pass).

grep -R -n "proxy_ssl_" /etc/nginx/

2Fix

Point nginx at a CA bundle that signed the backend's certificate, and set the name to check.

proxy_ssl_verify on;
proxy_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt;
proxy_ssl_name backend.example.net;

3Verify

Reload and request through nginx.

sudo nginx -t && sudo systemctl reload nginx

Confirmed by nginx.org

Did this fix it?

How do I stop it coming back?

  • Write the three directives (server name, Host, verification) together whenever you proxy to an HTTPS backend.
  • Test the backend with openssl s_client before blaming nginx.
  • Keep upstream names, not IP addresses, in proxy_pass for hosted platforms.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.