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

Fix Linux reverse proxy errors including SSL termination failures, missing X-Forwarded headers, WebSocket proxying issues, and backend routing problems. This guide covers everything you need to know about this topic, including common causes, step-by-step solutions, and answers to frequently asked questions.

Here are the key things to understand: 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. Understanding these fundamentals will help you diagnose and resolve this issue more effectively.

The most common reasons this occurs include: 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. Identifying the root cause is the first step toward finding the right solution.

To resolve this, follow these recommended steps: Set 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;'. For WebSocket: add 'proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade";'. Configure backend to trust proxy headers (Express: trust proxy, Django: SECURE_PROXY_SSL_HEADER). Use 'proxy_set_header Host $host;' to preserve the original hostname for the backend. Test SSL certificate: 'openssl s_client -connect yourdomain.com:443 -servername yourdomain.com'. If these steps do not resolve the issue, consider consulting additional resources or a qualified professional.

This article is part of our Linux Error Codes collection on Error Codes Wiki. We provide comprehensive, up-to-date information to help you find solutions quickly.