Nginx 502 Bad Gateway & 504 Gateway Timeout: Diagnose and Fix Upstreams

Nginx 502 Bad Gateway and 504 Gateway Timeout errors usually mean Nginx is working as a gateway or reverse proxy but cannot complete communication with the upstream application correctly.

The fastest way to troubleshoot them is to identify which upstream failed and then test that upstream directly.

Last verified: September 24, 2026. Package paths, service names, PHP versions, Nginx builds, control-panel layouts and upstream architectures differ between servers; verify the active configuration before changing production values.

---

1. Nginx 502 vs 504: Quick Diagnostic Matrix

---

2. Capture the Incident Before Restarting Anything

Repeatedly restarting Nginx, PHP-FPM or the application can restore service while destroying useful timing/context. Before changing anything, capture:

• The exact URL and HTTP method.
• The observed status code.
• Date, time and timezone.
• Whether the failure is constant or intermittent.
• Whether it affects one hostname/path or the entire site.
• The matching Nginx error-log line.
• The upstream address/socket from the log or active configuration.
• PHP/app/system logs for the same time window.
• If Cloudflare is involved, the Ray ID and the result of /cdn-cgi/trace.

For example:

date --iso-8601=seconds
curl -sv -o /dev/null https://example.com/
sudo tail -n 100 /var/log/nginx/error.log

Service names and log paths vary. Preserve the evidence before a restart whenever the site is stable enough to do so safely.

---

3. Identify the Actual Request Path

Do not change PHP-FPM settings until you confirm that the failing request is actually using FastCGI.

PHP / WordPress path

Browser
  ↓
Nginx
  ↓
FastCGI
  ↓
PHP-FPM
  ↓
WordPress / PHP app
  ↓
Database / external APIs

Reverse-proxy path

Browser
  ↓
Nginx
  ↓
proxy_pass
  ↓
Node / Python / app server
  ↓
Database / external APIs

The diagnostic branch changes depending on whether Nginx uses fastcgi_pass, proxy_pass or an upstream group.

Inspect the configuration Nginx is actually loading rather than assuming the file you edited is active:

sudo nginx -T 2>&1 | grep -nE 'server_name|fastcgi_pass|proxy_pass|upstream|fastcgi_.*timeout|proxy_.*timeout'

nginx -T prints the effective configuration and can expose internal addresses, credentials embedded in URLs, headers or other sensitive values. Do not paste unredacted output into public tickets or forums.

---

4. Read the Nginx Error Log Before Editing Anything

sudo tail -f /var/log/nginx/error.log

Depending on the distribution or control panel, the path may differ. Also correlate Nginx's service journal when systemd is used:

sudo journalctl -u nginx --since "30 minutes ago"

High-value messages include:

• connect() failed
• Connection refused
• No such file or directory
• Permission denied
• upstream timed out
• upstream prematurely closed connection
• upstream sent invalid header
• no live upstreams

---

5. Map the Error Message to the Likely Failure

---

6. Check PHP-FPM Service Status

For a PHP site, confirm that the correct FPM service is running.

sudo systemctl status php8.3-fpm
systemctl list-units --type=service | grep -i fpm
sudo journalctl -u php8.3-fpm --since "30 minutes ago"

Replace php8.3-fpm with the actual service name installed on the server.

---

7. Verify the FastCGI Socket or TCP Listener

A common 502 appears after a PHP upgrade because Nginx still points to an old socket.

fastcgi_pass unix:/run/php/php8.3-fpm.sock;

Check what actually exists:

ls -lah /run/php/
grep -R "^listen =" /etc/php/*/fpm/pool.d/

If FastCGI uses TCP instead:

fastcgi_pass 127.0.0.1:9000;
sudo ss -lntp | grep ':9000'

Fix the real configuration mismatch instead of creating a permanent symlink around an outdated socket path.

---

8. Check Unix-Socket Permissions

ls -l /run/php/php8.3-fpm.sock

A pool can use settings such as:

listen.owner = www-data
listen.group = www-data
listen.mode = 0660

These are examples. Use the actual Nginx/FPM users and groups for your server.

If Unix permissions look correct but logs still show Permission denied, check the server's mandatory access-control layer (for example SELinux or AppArmor) before weakening filesystem permissions globally. Do not “fix” a socket by making it world-writable.

---

9. Test HTTP Upstreams Without Nginx

For a proxy_pass application, test the backend directly.

curl -sv http://127.0.0.1:3000/
curl -sv -H 'Host: app.example.com' http://127.0.0.1:3000/

If the application exposes a lightweight readiness/health route, test that too. Preserve the same Host header or other required routing information when the backend uses virtual hosts.

If the service fails or is slow when accessed directly, Nginx is usually exposing an upstream problem rather than causing it.

For remote/containerized upstreams also verify routing, DNS, container networks, firewall/security-group rules and the address actually used by Nginx.

---

10. HTTPS Upstreams Can Fail on SNI or Certificate Expectations

If proxy_pass points to an HTTPS upstream, distinguish TCP reachability from TLS/virtual-host correctness.

Nginx's current proxy module keeps proxy_ssl_server_name off by default. A backend that requires SNI can therefore fail even though its port is reachable.

A configuration may require something like:

proxy_pass https://app.example.internal;
proxy_ssl_server_name on;
proxy_ssl_name app.example.internal;

Do not copy this blindly. Verify the upstream hostname, certificate, SNI requirement and whether certificate verification is intentionally configured. A TLS-handshake problem is not fixed by increasing proxy_read_timeout.

---

11. Compare the Public Path With the Origin Path

If a CDN or reverse proxy sits in front of Nginx, compare the proxied response with a direct origin test where it is safe and supported. This helps determine whether the failure exists at the origin, at the CDN/proxy layer, or only on one path.

curl -I https://example.com/
curl -v http://127.0.0.1:3000/

Use the appropriate Host header or local origin address for your architecture. Do not bypass production security controls merely for convenience.

---

12. Validate Nginx Before Reloading

sudo nginx -t
sudo systemctl reload nginx

Only reload after the syntax test succeeds. Keep a copy/versioned record of the previous working configuration so the change can be reversed quickly if the error rate or routing behavior worsens.

After reload, verify both the public route and the direct upstream path again; a successful nginx -t proves syntax validity, not application correctness.

---

13. PHP-FPM Can Be Running but Still Saturated

An active FPM service is not the same as healthy capacity. PHP documents pm.max_children as the number of child processes in static mode and the maximum child count in dynamic/ondemand mode; it therefore limits how many requests the pool can serve simultaneously.

Important directives include:

• pm
• pm.max_children
• pm.start_servers — dynamic mode only
• pm.min_spare_servers — dynamic mode only
• pm.max_spare_servers — dynamic mode only
• pm.max_requests

If all workers are busy, new requests can queue even though the service reports as running. Treat listen queue as the current backlog and max children reached as a historical counter since the pool started; neither value alone proves the correct remedy is simply “increase workers.”

Use the PHP-FPM Tuning Guide for pool sizing instead of copying a generic worker count.

---

14. Do Not Increase pm.max_children Blindly

Each additional PHP worker consumes memory. A safer process is:

1. Measure representative worker memory use.
2. Measure total available memory.
3. Reserve memory for Linux, Nginx, database, cache and monitoring.
4. Leave operational headroom.
5. Then calculate a worker ceiling.

A higher pm.max_children on an undersized server can trade queueing for swapping or OOM termination.

---

15. Use PHP-FPM Status Carefully

PHP's current FPM status documentation exposes signals including listen queue, active processes, max active processes and whether max children has been reached.

PHP-FPM can expose pool status metrics such as active processes, idle processes, listen queue and maximum active processes. The status endpoint should be restricted to trusted/internal access because it reveals request and resource information.

Where supported, pm.status_listen can create a separate status listener that remains reachable even when the main pool is busy.

---

16. Check for OOM Kills and Memory Pressure

journalctl -k --since "1 hour ago" | grep -Ei 'out of memory|oom|killed process'
dmesg -T | grep -Ei 'out of memory|oom|killed process'
free -h
ps aux --sort=-%mem | head

If the kernel killed PHP, Node, Python or the database, the gateway error may be a symptom of memory exhaustion.

---

17. Understand FastCGI Timeout Semantics

NGINX's current FastCGI module documentation defines fastcgi_read_timeout and fastcgi_send_timeout as inactivity intervals between successive read/write operations, not total request-duration limits.

NGINX currently documents these FastCGI defaults:

fastcgi_connect_timeout 60s;
fastcgi_send_timeout    60s;
fastcgi_read_timeout    60s;

The important detail is that fastcgi_read_timeout applies between successive reads from the FastCGI server. It is not simply a total PHP execution-time limit.

Likewise, fastcgi_send_timeout applies between successive writes while Nginx sends the request to FastCGI.

Application/PHP/FPM/database/network timeouts are separate layers. Raising Nginx above 60 seconds does not guarantee the application is allowed to run longer, and it can increase the number of requests holding workers/connections open while a dependency remains slow.

---

18. Reverse-Proxy Timeouts Are Separate

For proxy_pass applications, use the proxy module documentation; proxy_read_timeout is likewise measured between successive reads from the proxied server.

If the failing location uses proxy_pass, the proxy module controls the timeout behavior.

proxy_connect_timeout 30s;
proxy_send_timeout    60s;
proxy_read_timeout    60s;

Those numbers are illustrative. NGINX currently documents a 60-second default for proxy_read_timeout, and it also measures the interval between successive reads rather than the total response duration.

---

19. Buffers Are Not Generic 502/504 Fixes

Do not increase proxy_buffer_size, proxy_buffers, fastcgi_buffer_size or related values merely because the status is 502.

Buffer tuning belongs to a different evidence branch. For example, Nginx documents the first upstream response-header buffer separately; if logs specifically report an oversized or invalid upstream header, investigate the actual header/cookie size and then the relevant buffer directive.

A connection refusal, missing FastCGI socket, OOM kill or upstream read timeout will not be repaired by allocating larger response buffers.

---

20. 504 Errors Often Require Application Profiling

Investigate:

• Long PHP/application execution.
• Slow SQL queries or locks.
• Remote API latency.
• Large imports/exports.
• Image or document processing.
• WooCommerce scheduled actions.
• Object/file storage latency.
• Worker queues and concurrency.

The Nginx timeout is often where the problem becomes visible—not where it starts.

---

21. Database and External APIs Can Hold Workers Open

PHP may spend much of a request waiting on MySQL/MariaDB or a third-party service. Check slow queries, lock contention, storage latency, external HTTP calls and application-level timeouts before increasing gateway timeouts.

Object caching can reduce repeated database work for some workloads, but it cannot repair a stopped backend, a broken socket, a crashed process or an unavailable upstream.

---

22. Review WordPress Scheduled Work

Backups, imports, exports, image processing, WooCommerce scheduled actions and large mail queues can compete with normal visitor traffic.

For busy sites, consider whether predictable scheduled work should run through a system scheduler instead of relying entirely on visitor-triggered WP-Cron.

---

23. Use Caching Only Where the Request Is Cacheable

Possible layers include page cache, FastCGI cache, reverse-proxy cache, object cache and CDN cache.

Do not incorrectly cache authenticated, cart, checkout, account or other personalized traffic merely to hide insufficient application capacity.

---

24. Add Upstream Timing to Nginx Logs

For intermittent failures, log timing variables such as:

• $request_time
• $upstream_addr
• $upstream_status
• $upstream_connect_time
• $upstream_header_time
• $upstream_response_time

log_format upstream_timing
'$remote_addr request_id=$request_id '
'"$request" status=$status '
'request_time=$request_time '
'upstream=$upstream_addr '
'upstream_status=$upstream_status '
'connect=$upstream_connect_time '
'header=$upstream_header_time '
'response=$upstream_response_time';

Validate the full Nginx configuration before deploying a custom log format. If Nginx tries more than one upstream, the upstream address/status/timing variables can contain multiple values separated in the same order, which makes them useful for seeing retries/failover rather than just the final status.

Do not log secrets, authorization headers or request bodies merely to diagnose timing.

---

25. DNS Can Break Named Upstreams

If proxy_pass or an upstream uses a hostname instead of a fixed IP, verify DNS resolution from the Nginx host.

getent hosts app.internal.example
dig app.internal.example
curl -v http://app.internal.example:3000/

Container/service-discovery setups can also fail when Nginx resolves a stale or unreachable address. Treat DNS as part of the upstream path rather than assuming every 502 is a PHP problem.

Modern Nginx supports DNS resolver configuration for upstream groups as well, but resolver behavior depends on how the upstream is declared and the Nginx version/configuration. Verify the active config and resolution path instead of adding a public resolver blindly to production.

---

26. Docker and Container Networking Can Cause 502 Errors

Common mistakes include:

• Using 127.0.0.1 when the upstream runs in a different container.
• Using the wrong Docker network.
• Publishing a container port but pointing Nginx to the wrong host/port.
• Starting Nginx before the backend is ready.
• Using a container name that is not resolvable from the Nginx network.

Test connectivity from the same network namespace/context where Nginx runs. If Nginx itself is in Docker, a successful curl localhost:3000 on the host does not prove the Nginx container can reach that service. Test from the Nginx container/network or use the service name/address Nginx actually sees.

---

27. Upstream Groups Can Fail Differently

When Nginx load-balances multiple backends, inspect each backend, its connection limit, failure state and retry behavior. A 502 can occur when no usable upstream can be selected or when selected backends fail.

Be especially careful with automatic retries for POST/PATCH or other state-changing requests. A retry can duplicate an operation if the first backend processed it before the connection failed.

Current Nginx defaults for both proxy_next_upstream and fastcgi_next_upstream are error timeout. Nginx normally does not pass an already-sent non-idempotent request such as POST/PATCH to the next upstream unless non_idempotent is explicitly enabled.

---

28. Cloudflare Adds Another Gateway Layer

Visitor
  ↓
Cloudflare
  ↓
Nginx
  ↓
PHP-FPM / application
  ↓
Database

Cloudflare's current 502/504 troubleshooting documentation says these errors can originate from either the origin server or Cloudflare itself, with origin-side problems being the most common. Identify the response source before changing Nginx or PHP-FPM.

For a reproducible Cloudflare incident report, preserve the timestamp/timezone, failing URL and the output of https://example.com/cdn-cgi/trace. Cloudflare-generated error responses can also expose diagnostic headers such as cf-error-type and cf-error-origin; those headers are not present on errors simply forwarded from your origin.

For origin reachability problems specifically, see the Cloudflare Error 521 Guide.

---

29. Watch TTFB Before Gateway Failures Become Frequent

Rising backend response time can be an early capacity or application warning. Monitor it alongside error rate, PHP-FPM queueing, database latency, CPU, memory and cache effectiveness.

Use the TTFB & Server Response Time Guide for deeper response analysis.

---

30. When Hosting Capacity Is Actually the Problem

Consider more resources or a different architecture only when monitoring shows sustained constraints such as:

• CPU saturation.
• Memory exhaustion/OOM kills.
• Persistent PHP-FPM queueing.
• Database resource saturation.
• Storage latency.
• Repeated service crashes under legitimate traffic.

One slow plugin request is not enough evidence to justify a server migration.

If sustained infrastructure limits are demonstrated with monitoring, use the Shared vs VPS vs Cloud Hosting Guide to compare architecture options.

---

31. Reproducible 502/504 Incident Worksheet

The audit for this article calls for evidence instead of “zero-error” claims. Use this worksheet for a real incident or staging reproduction; leave values blank until actually measured.

For intermittent failures, repeat the same request/workload enough times to establish whether the failure rate actually changed. Do not claim “zero errors” from one successful retest.

---

32. Nginx 502 Troubleshooting Workflow

502 Bad Gateway
      ↓
Capture URL/method/time + exact log evidence
      ↓
Read Nginx error log
      ↓
Identify FastCGI / proxy upstream
      ↓
Is upstream running?
      ↓
Verify socket / IP / port
      ↓
Verify permissions / DNS / networking
      ↓
Check crash / OOM evidence
      ↓
Test upstream directly
      ↓
Inspect application logs
      ↓
nginx -t
      ↓
Retest

---

33. Nginx 504 Troubleshooting Workflow

504 Gateway Timeout
      ↓
Capture URL/method/time + exact log evidence
      ↓
Read Nginx error log
      ↓
Identify FastCGI / proxy upstream
      ↓
Measure upstream timing
      ↓
Check app / PHP queue
      ↓
Check database / external APIs
      ↓
Check CPU / RAM / storage
      ↓
Profile slow work
      ↓
Verify relevant timeout directive
      ↓
Change timeout only if long-running behavior is legitimate
      ↓
Retest under realistic load + compare timings

---

34. Common Nginx 502/504 Mistakes

• Restarting Nginx repeatedly: the failing component may be the backend, and restart-first troubleshooting can erase useful evidence.
• Increasing every timeout: longer waiting does not repair the cause.
• Increasing buffers for a timeout/refusal: buffer directives only belong to an evidence branch that actually points to response-header/buffering limits.
• Editing FastCGI directives for a proxy_pass app: use the right module.
• Setting pm.max_children from a generic table: worker memory varies by workload.
• Ignoring OOM events: terminated workers can look like random gateway errors.
• Assuming a socket path after a PHP upgrade: verify the real listener.
• Ignoring DNS/container networking: named or containerized upstreams can resolve/reach incorrectly.
• Testing from the wrong network namespace: host-local reachability does not prove an Nginx container can reach the same backend.
• Ignoring HTTPS upstream SNI: a reachable TLS port can still fail if the backend expects the correct server name.
• Ignoring database/API latency: the upstream may be healthy but blocked on dependencies.
• Testing only through Cloudflare: isolate the origin/upstream where safe.
• Enabling non-idempotent upstream retries casually: state-changing requests can be duplicated without application-level idempotency.
• Claiming “zero errors” from one retest: repeat the same workload and preserve before/after evidence.
• Upgrading hosting first: application defects can remain on a larger server.

---

35. Related Digital Bhatti Guides

• PHP process management: PHP-FPM Tuning Guide.
• Response diagnosis: TTFB & Server Response Time.
• Cloudflare origin reachability: Cloudflare Error 521.
• Object caching: Redis vs Memcached.
• Web-server architecture: LiteSpeed vs Nginx vs Apache.

---

Nginx 502 & 504 Checklist

• Capture URL, method, timestamp/timezone and matching log evidence before restart where possible.
• Read the error log first.
• Identify FastCGI vs proxy_pass.
• Confirm the upstream service is running.
• Verify socket, IP, port and DNS.
• Check Unix-socket permissions.
• Test HTTP upstreams directly with the correct Host/routing context.
• For HTTPS upstreams, verify SNI/certificate expectations.
• Check container networking where relevant.
• Run nginx -t before reload.
• Check PHP-FPM queueing and pm.max_children.
• Check OOM logs and memory pressure.
• Investigate DB and external API latency.
• Use the correct FastCGI or proxy timeout directive and remember read/send timeouts are inactivity intervals.
• Do not tune buffers unless logs point to header/buffering constraints.
• Do not increase timeouts blindly.
• Add upstream timing and request IDs when intermittent failures need evidence.
• Review retry behavior before changing proxy_next_upstream / fastcgi_next_upstream.
• Separate Cloudflare errors from origin errors.
• Upgrade infrastructure only after sustained capacity limits are demonstrated.

Frequently Asked Questions

What is the difference between Nginx 502 and 504?

A 502 generally means Nginx could not obtain a usable response from the upstream. A 504 generally means the required upstream communication did not complete within the relevant timeout. Use the error log to identify the actual failure.

Can a wrong PHP-FPM socket cause 502 Bad Gateway?

Yes. If Nginx points to a socket that does not exist, no longer matches the installed PHP version or cannot be accessed because of permissions, FastCGI communication can fail.

What does “connect() failed (111: Connection refused)” mean?

It usually means Nginx tried to connect to the configured upstream address/port but nothing accepted the connection. Check whether the service is running and listening on the expected address.

What does “upstream timed out” mean?

It means Nginx waited for upstream communication and no required data arrived within the configured interval. Investigate application work, worker queues, databases, external APIs and then verify the relevant timeout.

Should I increase fastcgi_read_timeout for every 504?

No. NGINX defines fastcgi_read_timeout as the timeout between successive reads from FastCGI. First find why the backend is not producing data within that interval.

Can low pm.max_children contribute to 504 errors?

Yes. If all PHP-FPM workers are busy, requests can queue. But increasing the value without enough memory can create swapping or OOM problems.

Can Redis fix a 502?

No. Redis cannot restart PHP-FPM, repair a missing socket, fix a refused connection or recover a crashed application. Object caching is a separate optimization.

Can Cloudflare cause a 502 or 504?

Yes. Cloudflare documents that 502/504 errors can originate either at the origin or within Cloudflare. Most cases are origin-side, so identify the response source before changing server configuration.

When should I upgrade the server?

Consider more resources when monitoring shows sustained CPU, memory, PHP-FPM, database or storage constraints under legitimate traffic after application problems have been investigated.

What Nginx versions are current?

At this article's September 24, 2026 verification, nginx.org lists stable 1.30.5 and mainline 1.31.6. Use a supported patched package for your distribution/vendor, but do not treat a version upgrade as a substitute for gateway-error diagnosis.

Should I increase proxy_buffer_size to fix a 502?

Only when the log evidence points to an upstream response-header/buffer problem. A refused connection, missing socket, timeout, OOM kill or crashed backend is a different failure branch and larger buffers will not repair it.

Can an HTTPS proxy_pass fail even when the upstream port is open?

Yes. TLS/SNI or certificate expectations can still fail. Nginx keeps proxy_ssl_server_name off by default, so backends that require SNI need deliberate configuration rather than a timeout increase.

Can Nginx retry a failed POST request on another upstream?

By default, Nginx does not normally pass an already-sent non-idempotent request such as POST/PATCH to the next server. Explicitly enabling non_idempotent retries can create duplicate operations unless the application itself provides idempotency.

How do I prove that a 502/504 fix worked?

Repeat the same request or workload, compare the exact error logs and upstream timing before/after, confirm the direct upstream path is healthy, and verify the gateway error does not recur across repeated tests. One successful request is not evidence of a zero-error system.