Worked example: a synthetic nginx 502 and 504 triage matrix

This is a synthetic example, not a client case

Everything below is invented to show the method. The site, addresses, durations and results are made up and no real server, run or customer is described. The case: a small web app is served by nginx at an example hostname. Two routes fail. Visiting /dashboard/ returns a 502 straight away, and exporting a report at /export/report/ returns a 504 after about a minute. The routes are written with the trailing slash because the location blocks below are prefix locations ending in a slash; the guide on proxy_pass and location matching explains what a request without the slash does. The matrix shows how a reviewer would separate the two faults and what evidence closes each one.

• Route /dashboard/ returns 502 immediately.
• Route /export/report/ returns 504 after a fixed wait.
• Other routes work, and restarting nginx changes nothing.

The triage matrix

The columns are the evidence a reviewer collects for each failing route. A direct request bypasses nginx and goes to the application's own address, so it shows whether the application answers at all and how long it takes. The error stage comes from the nginx error log for the same timestamp. All values are synthetic.

If the matrix is wider than the box, scroll horizontally to read every column. Keyboard: focus the matrix and use Left/Right.

route            status  nginx log stage      direct request to app      finding
/dashboard/      502     connecting           connection refused :3001   app not listening on :3001 (config says :3001, app uses :3000)
/export/report/  504     reading response     200 after 74 s             slow route; read timeout is 60 s
/health          200     -                    200 in 0.02 s              fine

Reading the first row

The dashboard fails at the connecting stage, and a direct request to the configured port is refused. The application is healthy on a different port than the one in the proxy_pass line. The fix is a one-line change of the upstream address, tested with the configuration check and then reloaded. Raising a timeout would change nothing, because the failure happens before any waiting.

• Before: proxy_pass http://127.0.0.1:3001; inside location /dashboard/
• After: proxy_pass http://127.0.0.1:3000; inside the same location
• Evidence of fix: the route returns the agreed status on 20 consecutive requests and the log has no connecting-stage entries for it.

If the matrix is wider than the box, scroll horizontally to read every column. Keyboard: focus the matrix and use Left/Right.

location /dashboard/ {
    proxy_pass http://127.0.0.1:3000;   # was :3001
}

Reading the second row

The report route reaches the application and the application takes 74 seconds, which is longer than the 60 second default read timeout. The right response is not to lift every timeout. It is to give this one location a read timeout above the measured duration and to record that the proper fix is a background job. The handover table records the route, the measured duration, the old value, the new value and why.

• Measured duration: 74 s (synthetic).
• Change: read timeout for /export/report/ only, set above the measured worst case.
• Note: if the report grows, move the work to a background job; the timeout is a stopgap.

If the matrix is wider than the box, scroll horizontally to read every column. Keyboard: focus the matrix and use Left/Right.

location /export/report/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_read_timeout 120s;   # measured worst case 74 s; other routes stay at the 60 s default
}

What a buyer should receive

A cause statement per route with the log stage and the direct-request result, the configuration diff, the result of the configuration test, the 20-request results per URL, the clean log excerpt for the test window, and the steps to revert. If any of these is missing, the repair is not evidenced. Use this layout when asking any provider to fix a gateway error. It is a checklist, not a runnable fixture, and it does not describe delivered work.