Linux Nginx Error Codes — 502, 504, 413 & Upstream Failures

Fix common Nginx errors including 502 Bad Gateway, 504 Gateway Timeout, 413 Request Entity Too Large, and upstream connection failures. 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: Nginx errors are logged to /var/log/nginx/error.log by default. 502 Bad Gateway: upstream (backend) returned invalid response or is not running. 504 Gateway Timeout: upstream did not respond within proxy_read_timeout. 413 Request Entity Too Large: request body exceeds client_max_body_size (default 1MB). Connection refused: upstream is not listening on the configured address/port. Understanding these fundamentals will help you diagnose and resolve this issue more effectively.

The most common reasons this occurs include: 502: backend application crashed, not running, or returning malformed response. 504: backend processing time exceeds Nginx timeout settings. 413: file upload or POST body exceeds client_max_body_size. Connection refused: backend not started or wrong port in upstream config. Permission denied: Nginx worker cannot connect to upstream socket. Identifying the root cause is the first step toward finding the right solution.

To resolve this, follow these recommended steps: Check Nginx error log: tail -f /var/log/nginx/error.log. For 502: verify backend is running — curl -v http://127.0.0.1:BACKEND_PORT. For 504: increase timeout — proxy_read_timeout 300s; proxy_connect_timeout 300s;. For 413: increase limit — client_max_body_size 50M; in server or location block. Test config: nginx -t, then reload: systemctl reload nginx. 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.