WIUNIX ACADEMY
Nginx 502 and 504: identify the failing upstream phase
Page 2 of 3. Review the earlier steps and prerequisites before continuing.
YOUR SYSTEM. YOUR STEPS.
Where are you working?
Choose your OS and version. The prerequisites, commands and troubleshooting follow your environment.
USE YOUR OWN VALUES
Configure this tutorial
Set the example values for your environment; related explanations and copy panels update together. Never enter passwords, private keys or tokens. Values stay in this tab and are not sent to the server or share links. Check actual DNS, certificates and network policy before running commands.
Different IP addresses, domains or ports? Open the settings below, change the values and select “Apply to tutorial”, then copy the updated commands.
Set values for my environment5 editable values
LET’S BUILD
Read the phase named by Nginx
Inspect a bounded tail of the package’s existing error log. Connection refused points first to listener/address/lifecycle; timed out while connecting points toward network reachability or a full accept backlog; timed out while reading response header points toward work before headers. Prematurely closed connection can indicate a crashing worker or protocol mismatch. A log path can be customized; use the actual configured path if this one differs.
Authorized Linux terminal
sudo tail -n 120 -- '/var/log/nginx/error.log'Correlate the UTC time, selected server and upstream phase. A browser status or an old unrelated error line is insufficient.
Add timing only when existing logs cannot distinguish the cause
If the current access log already has these fields, reuse it. Otherwise the following optional fragment belongs inside the existing http block, with the access_log line enabled only for the affected server/location. It deliberately omits URI, query, cookies, authorization and client IP. Keep the original configuration privately and use the owning change procedure; this is not a complete nginx.conf replacement. The operator must define retention and rotate the short diagnostic log.
File contents — not a shell command
# http context
log_format academy_phase escape=json
'{"id":"$request_id","status":$status,'
'"upstream":"$upstream_addr","upstream_status":"$upstream_status",'
'"connect":"$upstream_connect_time","header":"$upstream_header_time",'
'"response":"$upstream_response_time","total":"$request_time"}';
# affected server/location context only
access_log /var/log/nginx/academy-phase.log academy_phase;LET’S BUILD
Validate before a graceful reload
Only if you deliberately changed the selected configuration, test it before reload. A syntax failure leaves the old running configuration active; correct the file or restore the exact before copy rather than restarting blindly. A successful syntax check does not establish reachability or application health.
Authorized Linux terminal
sudo nginx -t && sudo systemctl reload nginxValidation and reload both succeed. Repeat the single public/private probe and inspect only its time window.
Interpret timings across attempts
Upstream timing fields are strings because retries can produce multiple values separated by commas or colons; do not parse them as one scalar. A dash can mean no usable measurement. A low connect time and high header time suggest time spent after connection and before response headers, but do not identify the SQL query. Compare request traces and database/worker metrics before deciding what to change. One fast health endpoint does not prove a slow business transaction is healthy.
Choose the correct deadline instead of raising every timeout
The connect timeout covers connection establishment. The read timeout limits the gap between successive reads, not the total transaction duration. An application sending occasional bytes may run much longer. Align client, edge, Nginx and application deadlines with the real operation; use asynchronous jobs for work that outlives an interactive request. A larger proxy deadline can retain more occupied connections and worsen overload. Retry policy for non-idempotent writes needs an application-level duplicate-prevention design.
Undo only diagnostic changes and keep the incident evidence
The read-only probes need no rollback. If you added the timing fragment, remove only that temporary log binding and format through the same editor/change procedure, validate and reload. Preserve the original production log, retained incident window and application configuration. Reverting a diagnostic log does not repair the backend. After the actual cause is fixed, repeat public and private probes and confirm business health over an agreed observation window.
Authorized Linux terminal
sudo nginx -t && sudo systemctl reload nginxTemporary instrumentation is removed, normal logging remains and the repaired operation meets its actual service deadline.