Job nginx-gateway-errors-502-504-one-site · revised 11 October 2026
Fix 502 or 504 gateway errors on one site served through nginx
The named pages of one nginx site stop returning 502 or 504. The cause is found in the error log, the change is tested before reload, and the way back is written down.
You might be seeing
- Named pages return 502 Bad Gateway while nginx itself is up and serving other pages
- A slow page or upload ends in 504 Gateway Timeout after a fixed wait
- The errors clear for a while after nginx or the app is restarted and then return
No passwords, keys, card details or admin invites needed to start.
What usually happened
nginx returns 502 when it cannot get a valid response from the upstream application and 504 when the upstream gives no answer in time. The causes differ: an upstream that is not listening where nginx expects it, a socket nginx cannot open, an app that crashed or is restarting, a request that legitimately takes longer than the proxy timeouts, or a retry setting that repeats work. Restarting nginx or raising every timeout can hide the real cause, hold worker connections open for a slow endpoint, or repeat a request that changes data.
Who it’s for: A founder or developer whose site or app sits behind an nginx reverse proxy on a server they run, and whose visitors see a gateway error on specific pages.
Usually starts when: Visitors get 502 Bad Gateway or 504 Gateway Timeout on named URLs after a deploy, an app restart, a configuration change or a slow request.
The result: The named URLs of one nginx site return the agreed successful response on 20 consecutive requests, the error log shows no upstream connect or timeout entries for them during the test, and the configuration change passed nginx's own configuration test before it was reloaded.
Check whether this job fits
Four checks that decide whether this fixed job fits. Your answers stay on this page unless you choose to email them.
Checks you can run yourself
Read the error behind the status
Ask the person who administers the server to find the file named by the error_log directive and read the end of it just after a failure. The first command prints the directive; it only reads.
sudo nginx -T 2>&1 | grep error_logLook for: A line that names the upstream address and what nginx was doing when it failed. A failure while connecting points to an application that is not listening. A failure while waiting for a response points to a slow application or a timeout setting.
Check that a pending edit would load
This checks syntax and the files it refers to, and does not change the running server.
sudo nginx -tLook for: A message that the syntax is ok and the test is successful. An error here means the next reload would keep the old configuration.
What you get
- A written cause statement with the log lines that show it
- The configuration diff, the steps to apply it and the steps to revert it
- Before and after request results for each named URL, and a note of anything in the application that nginx cannot fix
Included
- One nginx server block and up to three named URLs or routes that return 502 or 504
- A read of the error and access logs for the failing window, with secrets and visitor data removed
- Diagnosis of the upstream address, port or socket, whether the application is listening, and the proxy timeout and retry settings that apply to those routes
- The smallest configuration change, tested with nginx's configuration check and applied with a graceful reload
Not included
- Rewriting the application or making slow application code faster
- Errors shown by a CDN, a cloud load balancer or a hosting panel in front of your server
- FastCGI, uwsgi or gRPC upstreams: this job covers HTTP upstreams reached with proxy_pass, and the others are quoted
- A review of the whole nginx configuration, load balancing across several servers, or any uptime or response-time promise
- Certificate repair or hardening beyond the lines that cause the named errors
How we know it’s done
Agreed with you before work starts. Each check produces evidence you keep.
Each named URL returns the agreed status and a body check string on 20 consecutive requests made through nginx from outside the server.
Evidence: The 20 results per URL with timestamps.
for i in $(seq 20); do curl -sS -o /dev/null -w '%{http_code}\n' https://yourbusiness.co.uk/report; doneDuring the test window the nginx error log has no upstream connect, timeout or invalid-response entries for the named routes.
Evidence: A redacted error-log excerpt that covers the whole test window.
The changed configuration passes nginx's configuration test before reload, and the diff touches only the named server block and the lines listed in the cause statement.
Evidence: The configuration test output and the complete diff.
sudo nginx -tReverting with the written steps restores the earlier configuration, which passes the configuration test again.
Evidence: The revert rehearsal output on a copy, or in the agreed change window.
Where the cause is a request slower than the proxy read timeout, the handover names the endpoint, its measured duration and the timeout in force, and no timeout is raised on a route that was not failing.
Evidence: A table in the cause statement of route, measured duration, old and new timeout.
Sign-off. You sign off when the 20-request check passes, the error log is clean for the test window and the configuration test and revert steps are accepted. Payment follows sign-off.
If it fails. If the named URLs still fail after the agreed change, you do not pay for this fixed scope and you keep our findings. If the cause lies in the application or in a service in front of nginx, we say so with the evidence and stop rather than keep adjusting nginx.
When it fits, and when we stop
It fits when
- You run the nginx server and can send the relevant error-log lines with secrets removed
- The failing URLs can be requested on demand, or the errors occur often enough to appear in the log within the test window
- The upstream is an HTTP service on the same host or a private network reached with proxy_pass
- Someone can reload nginx in an agreed window
We stop and tell you if
- The error page comes from a CDN, load balancer or another machine in front of this nginx
- The upstream is down because of a full disk, an out-of-memory kill or a hardware fault on the host: that is a separate repair
- The errors appear only under heavy load that cannot be reproduced on a named route
- There are signs the server has been compromised
What could go wrong
The handover includes the exact lines before and after. Restoring the previous configuration file and reloading nginx puts the site back as it was. nginx keeps running the old configuration if a new one fails its check, so a mistyped edit does not take the site down at reload.
Scroll the table sideways to read it all.
| Risk | How we handle it |
|---|---|
| Raising a timeout turns a visible 504 into long-held connections that tie up worker capacity for a slow endpoint. | Raise it only for the named route, record the measured duration and the value chosen, and name the application fix as the proper remedy. |
| A retry setting repeats a request that changes data, such as a payment or an order. | Check the retry settings that apply to each route and do not allow retries of POST, LOCK or PATCH requests once they have reached the upstream. |
| A reload with a hidden error leaves the old configuration running and the change not applied. | Run the configuration test first and check the live behaviour of the named URLs after the reload, not only the reload command. |
An independent reviewer checks that no timeout was raised for a route that was not failing, that retries do not repeat requests that change data, and that the change touches only the named server block.
How we deliver
We arrange the work and independent review, then show you the result against the agreed checks. You keep authority over your systems.
- Agree the site, the named URLs, the response each should return and a test window in writing
- Read the redacted error and access logs and sort the failures into cannot connect, invalid response and no response in time
- Confirm the upstream address, port or socket, whether the application is listening there, and the timeout and retry settings that apply to the named routes
- Reproduce a failure on a named URL, or record the log evidence if it cannot be triggered on demand
- Prepare the smallest change and test it with nginx's configuration check on a copy of the configuration
- Independent review of the change, especially any timeout or retry value
- Hand over the diff and steps, then run the 20-request check and read the log for the test window after your administrator reloads
This is a one-off job, not emergency cover or a subscription. We confirm eligibility, the total price, a start window and a delivery date before you accept. Work starts only after agreed inputs, secure access, any licences and necessary permissions are in place. Hosting, platform and supplier charges are excluded unless the written quote includes them. No charge or booking is created by an enquiry.
Need to keep it working?
If errors keep returning, ask about a monthly server review. This job covers the named routes only and is not emergency cover.
Ongoing work is separately scoped and quoted: no monitoring, response-time guarantee or automatic subscription is included in this job.
Explore an ongoing engineering lane, or mention the responsibility you need in your enquiry.
What you can check
This is a new service. We have not delivered this job for a client yet.
Other ways to get this done
- The nginx documentation lists the proxy timeout directives and their defaults, which is often enough for a team that can read its own logs. nginx.org
- If a CDN or load balancer sits in front of nginx, its own error documentation and dashboard are the first place to look.
Questions
Can you just raise the timeout?
Only where the log shows the application was still working and the request is meant to take that long. Otherwise a longer timeout only delays the error. The handover records the reason for each value.
Will this keep the site up?
We fix the cause found for the named routes and test them. We do not promise uptime, and the application can still fail for reasons outside nginx.
Does this cover errors from my CDN?
No. An error page from a CDN or load balancer comes from that service. Check it and your origin's reachability first.
What if the cause is in my application?
We tell you what the log shows and what the application must change. Fixing the application is a separate bug-fix job with its own test.
Send an enquiry
Send us
- The failing URLs, when the errors began, and what changed shortly before
- Twenty to fifty error-log lines around one failure, and the proxy_pass and timeout lines of the server block, with credentials and visitor addresses removed
- Where nginx's error log lives on your server, if you know
- Do not send server logins, private keys or whole configuration files in the first enquiry
Later, once you agree
- The nginx configuration for the site, read-only, through the agreed handoff
- A way to request the failing URLs during a test window
- Your administrator for the reload, or a time-limited account you create and revoke
- A company-controlled secure handoff agreed before access: no live passwords, keys, private code or customer records by ordinary email.
You own the server, the nginx configuration and the application. We read redacted logs and configuration, test the change against a copy of the configuration where we can, and hand over a diff with steps. Your administrator reloads nginx, or you create a time-limited, least-privilege account for that and revoke it afterwards, agreed in writing. We never ask for a root password in the first enquiry.
Email fallback: open your mail app
If website submission is unavailable, review and send the fallback email yourself. An email fallback is not a website receipt. Or write to hello@syntheticindustry.ai with “nginx-gateway-errors-502-504-one-site” as the subject.