Troubleshoot Nginx 502 and 504 errors on your VPS

Identify which component returned the error

A gateway error can originate from Nginx, an application gateway or a proxy in front of your VPS. Record the URL, exact error, timestamp and whether every request fails or only one action. A 502 commonly points to an invalid or failed upstream response; a 504 indicates a gateway timed out waiting. Neither code identifies the root cause by itself.

This guide is for websites you administer on a VPS. For an error on CloudExa's own control panels, send support the panel URL and request ID instead of changing your guest firewall to repair a provider-side service.

Read the matching logs

Keep your current access session open. Locate the active Nginx server block and configured access/error logs. Debian and Ubuntu packages commonly use /var/log/nginx/, but configuration can select other paths.

sudo nginx -t
sudo journalctl -u nginx --since "30 minutes ago" --no-pager

Read the error-log entry matching a failed request. Connection refused, permission denied, upstream timeout and a prematurely closed connection suggest different checks. The service journal may show startup failures while request details are in the configured error log. Preserve both when relevant.

Configuration dumps can expose private upstream addresses, headers or credentials. Review them locally and redact sensitive values before sharing. Do not publish the entire Nginx configuration just to show one error.

Test the upstream separately

Find the actual proxy_pass or FastCGI destination. Check whether the application service is running and listening on its expected interface, TCP port or Unix socket. For a confirmed local HTTP upstream on port 3000, a bounded test might be:

curl --connect-timeout 3 --max-time 10 -I http://127.0.0.1:3000/

Replace that address with your real upstream. Some applications do not support HEAD requests or need a particular Host header, so interpret the result accordingly. A FastCGI socket is not an HTTP server and cannot be tested with this command.

If the application fails locally, inspect its own logs, database connections and available memory/disk before changing Nginx. For Unix sockets, verify the owning service and intended permissions. Avoid granting world-writable access to the socket or running the application as root to bypass an error.

Fix the cause before extending timeouts

A slow database query, stuck external API call or exhausted worker pool can produce a timeout even when the process is active. Compare a simple health request with the failing operation. Longer timeouts can tie up more resources and conceal a recurring problem.

For HTTP proxying, proxy_connect_timeout controls establishing the upstream connection, while proxy_read_timeout controls the interval between successive upstream reads. FastCGI has separate directives. Change only the appropriate location after understanding the workload.

Validate and keep the previous configuration

Back up the specific file before editing it. Run sudo nginx -t and reload Nginx only when validation succeeds. Test the failing action and another normal route, then check both proxy and application logs. If a tested change worsens behaviour, restore the saved configuration and validate again.

Do not open a private application port to the entire internet as a diagnostic shortcut. If the failure remains, provide support the affected route, times, upstream test result and redacted matching log lines.