A 502 Bad Gateway website troubleshooting process works best when you trace the request through each service. The browser sends a request, a proxy or load balancer receives it, and the proxy contacts a web server or application process. A 502 response usually means one layer received an invalid or unusable response from the next layer.
This error does not identify the failed component by itself. The proxy may be healthy while the application is stopped. Alternatively, the application may work locally while the public proxy cannot reach it. This guide provides a careful path from visible symptoms to useful evidence.
What a 502 error actually means
A gateway is a service that passes requests to another service. Common examples include a content delivery network, reverse proxy, hosting platform proxy, load balancer, Nginx server, or Apache server configured as a proxy. The upstream is the service that receives the forwarded request.
When the gateway cannot obtain a valid upstream response, it may return HTTP status 502. Causes include a refused connection, a closed socket, malformed headers, an application crash, or an upstream timeout that the proxy reports as a gateway failure. Exact behavior depends on the proxy and hosting stack.
Therefore, 502 Bad Gateway website troubleshooting should not begin with repeated refreshes or an immediate reboot. Record the time, affected URL, HTTP method, client network, and response headers first. Those details help match the browser symptom with server events.
Map the request path before changing anything
Write down the likely path in plain language:
- A browser or API client sends an HTTPS request.
- DNS directs the hostname to a public service.
- A CDN, firewall, or reverse proxy accepts the connection.
- Next, the proxy connects to a web server or upstream application.
- Then, the application returns content, headers, and a status code.
- Finally, the response travels back through the proxy to the client.
A hosted website may contain more layers than this list. Your provider might hide the web server, application runtime, or database behind a managed platform. In that case, gather the same evidence and ask the host which layer owns each log.
For a useful baseline, compare the failing page with a static file, a health endpoint, and a known working page. Do not create a new diagnostic endpoint that exposes secrets. A static file tests the proxy and web server without invoking the application.
The article Why the Technical Troubleshooting Process Should Start With Evidence explains why timestamps and controlled tests matter before a repair.
Start with browser and public checks
Test the exact URL in a private browser window. Then test from a second network, such as a phone hotspot. If only one network fails, investigate local DNS, filtering, or connectivity before changing the server.
Capture the status code and response headers with an approved tool. A command such as curl -I https://example.com/path requests headers only, but it is not appropriate for every application. Replace the example hostname, and avoid sending credentials or destructive methods.
Look for headers that identify the responding layer. Some proxies add a request ID, cache status, server name, or upstream timing. These values vary by provider, so treat them as clues rather than proof. Save the complete output and note the test time in UTC if possible.
Check whether the error affects every URL. A site-wide 502 suggests a shared proxy, web server, runtime, or network problem. One dynamic route points more strongly toward a specific application path, plugin, integration, or query.
At this stage, 502 Bad Gateway website troubleshooting should distinguish a public failure from a browser-only symptom. Compare results from more than one client before changing production settings.
Inspect proxy and web server logs
Proxy logs often reveal the most important boundary. Search the relevant time window for messages such as “connection refused,” “upstream timed out,” “no route,” “prematurely closed connection,” or “invalid response.” Wording differs between products.
Match the public request to a log entry using the timestamp, hostname, path, client address, and request ID. A matching proxy entry proves that the request reached the proxy. It does not prove that the application received it.
Next, inspect the web server access and error logs. Confirm whether the web server accepted the proxied request. Compare the response status, upstream address, request duration, and bytes sent. A request that appears in the proxy log but not the web server log narrows the failure to the connection between those layers.
Keep logs intact while investigating. Do not rotate, delete, or truncate them merely to make the error disappear. If the server has limited storage, preserve a relevant time range before cleanup. Our guide to Linux server log analysis troubleshooting covers safe correlation across service and system logs.
Check whether the application process is alive
Many 502 incidents come from an application process that stopped, crashed, exhausted resources, or listens on a different socket than the proxy expects. The process might be PHP-FPM, Node.js, Python, a Java service, or another runtime.
Check the service status using the hosting platform’s console or approved server access. On Linux systems, systemctl status service-name can show whether a systemd-managed service is active. The service name differs by distribution and application, so do not copy a guessed name into production.
Read the service journal and application log around the first failure. Look for startup errors, dependency failures, permission problems, exhausted workers, fatal exceptions, or configuration parsing errors. A restart can restore service, but it may erase useful process state or hide the original cause.
Verify that the application listens where the proxy expects it. A TCP port is a numbered network endpoint. A Unix socket is a local file used for process communication. Either can fail because of a wrong path, permissions, ownership, or a changed configuration.
The ss manual documents socket inspection on Linux. Use it to confirm listeners and addresses, then compare those results with the proxy configuration.
Use local and upstream tests carefully
A local test helps separate public routing from the server and application. From the web server, request the upstream address directly with a safe method. Include the expected host header when virtual hosting requires it. A successful local response does not guarantee that the public proxy can connect.
Compare three results:
- Public request fails and local upstream request fails: investigate the web server, runtime, application, or its dependencies.
- Public request fails but local request works: investigate proxy routing, firewall rules, TLS settings between layers, or health checks.
- Static content works but dynamic content fails: focus on the application runtime, database, plugins, external APIs, or route-specific code.
Do not bypass authentication, disable a firewall, or expose an internal port just to make a test easier. A controlled test should change one variable and have a clear rollback. If you need to modify a proxy timeout or upstream address, save the current configuration first.
Investigate common application causes
Application failures often produce a 502 indirectly. A database connection may fail during page generation. A plugin or deployment may trigger a fatal error. An external API may stall. A worker pool may reach its limit, leaving the proxy without a timely response.
Check whether the incident began after a deployment, configuration change, plugin update, credential rotation, or hosting migration. Compare the first error timestamp with change records. If a recent change is strongly correlated, use the provider’s rollback process or a tested prior release.
For WordPress, review the PHP or application logs before disabling components. A staging test is safer than changing production blindly. The guide How to Recover WordPress After Plugin Conflict describes a controlled recovery approach.
Resource pressure also matters. Check memory, CPU, disk space, process limits, and open connections. A full disk can prevent logs, sockets, caches, or temporary files from working. Review Linux disk space troubleshooting before deleting files. Preserve evidence and confirm ownership before removing anything.
Apply a fix, then verify each layer
Once evidence identifies the failing boundary, choose the smallest suitable repair. That might mean correcting an upstream socket path, restoring a service configuration, rolling back a deployment, increasing a carefully justified worker limit, or resolving a dependency failure.
Validate configuration syntax before reloading a web server or proxy. Use the hosting provider’s documented test and reload procedure. A syntax check can catch malformed settings, but it cannot prove that the upstream service works.
After the change, test a static URL, a dynamic page, the previously failing route, and an authenticated function if appropriate. Repeat the test from an external network. Watch proxy, web server, and application logs during the verification window.
Document the trigger, evidence, change, rollback plan, and result. This record makes the next incident faster and helps a hosting provider act without guesswork. Google’s effective troubleshooting guidance also emphasizes hypotheses, evidence, and controlled testing.
When to escalate a 502 incident
Escalate quickly when the host controls the proxy, the error affects revenue or customer access, logs are unavailable, or the failure involves a managed database or platform service. Provide the hostname, affected paths, UTC timestamps, request IDs, test locations, response headers, and recent changes.
Avoid sending passwords, private keys, session cookies, or full customer data in a support ticket. Redact sensitive values while preserving the error structure. Ask the provider which layer returned the 502 and whether upstream health checks show failures.
502 Bad Gateway website troubleshooting is appropriate for careful evidence collection, not blind trial and error. If the proxy, web server, and application logs do not align, Tech Rescue Ops LLC can help trace the request path remotely and plan a reversible repair. This evidence-first approach keeps 502 Bad Gateway website troubleshooting focused and controlled.