◆Error Codes Wiki

Reverse Proxy Errors — SSL Termination, Header Forwarding, and Backend Connection Issues

Warningweb server

Overview

Fix Linux reverse proxy errors including SSL termination failures, missing X-Forwarded headers, WebSocket proxying issues, and backend routing problems.

Key Details

  • Reverse proxies handle SSL termination, load balancing, and routing to backend applications
  • X-Forwarded-For, X-Forwarded-Proto, and X-Real-IP headers must be set for backends to see client info
  • WebSocket connections require special proxy configuration for HTTP upgrade handling
  • SSL termination at the proxy means the backend receives HTTP, which can confuse URL generation
  • Health checks must distinguish between proxy layer and backend application failures

Common Causes

  • Missing X-Forwarded-For/Proto headers causing backend to see proxy IP instead of client IP
  • WebSocket upgrade not configured — proxy dropping the connection on WS handshake
  • SSL certificate on proxy not matching the requested domain
  • Backend receiving HTTP but generating HTTPS URLs, causing redirect loops

Steps

  1. 1Set forwarding headers in Nginx: 'proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme;'
  2. 2For WebSocket: add 'proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade";'
  3. 3Configure backend to trust proxy headers (Express: trust proxy, Django: SECURE_PROXY_SSL_HEADER)
  4. 4Use 'proxy_set_header Host $host;' to preserve the original hostname for the backend
  5. 5Test SSL certificate: 'openssl s_client -connect yourdomain.com:443 -servername yourdomain.com'

Tags

reverse-proxysslforwardingwebsocketheaders

Related Items

linux-nginx-502-bad-gateway

More in Web Server

linux-nginx-error-codesLinux Nginx Error Codes — 502, 504, 413 & Upstream Failures
Error
linux-apache-error-codesLinux Apache Error Codes — AH01630, AH00558 & Module Errors
Warning
linux-nginx-common-errorsNginx Common Errors — Configuration Test Failed and Upstream Timeout
Error
linux-nginx-502-bad-gatewayNginx 502 Bad Gateway — Upstream Server Connection and Proxy Errors
Error
linux-nginx-504-gateway-timeoutNginx 504 Gateway Timeout — Slow Upstream Response and Timeout Configuration
Error
linux-apache-mod-rewrite-errorsApache mod_rewrite Errors — URL Rewriting, .htaccess, and Redirect Loop Issues
Warning

Frequently Asked Questions

The proxy is not forwarding client IP headers. Add proxy_set_header X-Real-IP and X-Forwarded-For in your Nginx config. Configure your application to read these headers for the real client IP.