How do I debug WebSocket issues behind Nginx?
Check Nginx error logs (sudo tail -f /var/log/nginx/error.log). Verify the Upgrade and Connection headers are present. Test with nginx -t. Check the browser console for Socket.io connection errors. If using Cloudflare, enable WebSockets in the dashboard. Verify proxy_read_timeout is long enough.
Verify This Answer
Cross-check this information using these trusted sources:
More FAQs in Adding WebSocket Support to Nginx Socket.io Proxy Configuration
Add proxy_http_version 1.1, proxy_set_header Upgrade $http_upgrade, and proxy_set_header Connection 'upgrade' to the location block. These headers tell Nginx to upgrade the HTTP connection to WebSocket and forward it to the backend. Without them, Socket.io won't work.
Missing the Upgrade and Connection headers. WebSockets start as HTTP and upgrade to WebSocket. Without proxy_set_header Upgrade and Connection 'upgrade', Nginx doesn't forward the upgrade request, and the WebSocket connection fails. Also, HTTP/1.0 (default) doesn't support upgrades use proxy_http_version 1.1.
Set proxy_read_timeout and proxy_send_timeout to 86400s (24 hours). WebSocket connections are long-lived. The default 60-second timeout causes Nginx to close the connection, breaking the WebSocket. Long timeouts keep connections alive.
Still have questions?
Browse all our FAQs or reach out to our support team