Fixing 502, 503 and 504 errors

What 502 Bad Gateway, 503 Service Unavailable and 504 Gateway Timeout mean on TurboStack, how to diagnose them, and how to recover safely.

A 5xx status code means the web server reached your application but did not get a usable response back. On TurboStack this almost always points at the PHP backend rather than the visitor - and TurboStack gives you the tools to find the cause and recover quickly.

What each code means

Code	Name	What it usually means
502	Bad Gateway	The web server (nginx/apache) forwarded the request to PHP-FPM but got an invalid or empty reply. PHP-FPM is typically down, crashed, or restarting.
503	Service Unavailable	The backend is temporarily unable to handle the request. PHP-FPM is overloaded (no free workers), the app is in maintenance mode, or a service is mid-restart.
504	Gateway Timeout	PHP-FPM accepted the request but did not respond in time. The common cause is a slow query, a stuck external call, or a long-running request that exceeded the timeout.

In short: 502 = backend not answering, 503 = backend too busy, 504 = backend too slow.

Symptoms

Visitors see a plain "502 Bad Gateway", "503 Service Unavailable" or "504 Gateway Timeout" page instead of your site.
Errors are intermittent (overload) or constant (a crashed service).
The error often starts right after a deploy or a configuration change.

Diagnose it on TurboStack

Observe first, then act on the running server.

Health tab. Open the host's Health tab. Check Top Issues and the Services list for failing web-server or PHP checks. Also watch the CPU, RAM and swap cards - a host that is out of memory or pinned at 100% CPU will produce 502/503/504s under load.
History / Revisions. Open Revisions to see whether a recent publish or deploy coincides with when the errors began. If so, you have a strong candidate cause - and the option to roll back.
Logs over SSH. Connect via SSH and read the web-server and PHP-FPM error logs for the affected application. PHP fatal errors, "unable to connect" messages to the PHP-FPM socket, and "max_children reached" warnings each point to a different fix below.

Tip

If errors only appear under traffic spikes, treat it as an overload problem (503/504); if the site is down for every request, treat it as a crashed backend or a bad config (502).

Common causes and fixes

A configuration change has not been applied (502)

If you just changed the web-server config, the running server may still be using the old (or a broken) configuration. Apply the change safely:

tscli nginx reload

reload validates the configuration first and applies it without dropping live connections; use tscli nginx restart only if a full restart is genuinely needed. See the TurboStack CLI for details.

PHP-FPM is down or has crashed (502)

A crashed or stopped PHP-FPM pool is the most common cause of a constant 502. First reload the web server (above) so it reconnects to the backend. If PHP is genuinely stuck - workers hung and not recovering - you can force a clean restart as a last resort:

Warning

tscli php kill terminates all PHP-FPM workers on the host. Requests in flight are aborted, which can interrupt transactions. Use it only when PHP is stuck and nothing else has recovered it.

tscli php kill

PHP-FPM is then restarted by the platform and begins serving again. If PHP keeps crashing, look at the logs for the underlying fatal error (often a memory limit or a bug in newly deployed code).

PHP-FPM is overloaded - no free workers (503)

Under heavy traffic, every PHP-FPM worker can be busy, so new requests are queued or refused. Confirm with the Health tab (high CPU/RAM, "max_children" in the logs), then:

Resolve what is consuming the workers - a slow page, a crawler, or a traffic spike (see Why is my site slow? and High CPU and load).
If the host is simply too small for sustained load, increase the PHP-FPM worker pool via the per-application PHP-FPM tuning keys in Configure PHP, then publish. Raise worker counts with care - each worker uses memory, and over-provisioning can push the host into swap (see Out of memory).

Long-running requests and timeouts (504)

A 504 means PHP did not answer in time. Common culprits are slow database queries, large imports/exports, or external API calls that hang.

For genuinely long operations, raise PHP's max_execution_time via the PHP advanced options - see Override PHP settings. Note that the web server also enforces its own proxy/FastCGI read timeout.
Better still, move long jobs out of the web request entirely (queues, cron, CLI) so visitors are never blocked.

Stale bytecode after a deploy (502/500)

After deploying new code, PHP may still be running the old compiled bytecode, which can cause fatal errors until OPcache is refreshed:

tscli opcache clear

The first request afterwards is slightly slower while scripts recompile - this is normal. See Flush the OPcache.

Prevent it

Watch the Health tab and the fleet Monitoring dashboard so you catch overload and crashes before visitors do.
Clear OPcache as part of every deploy, and reload Nginx after config changes.
Keep heavy work (imports, reports, third-party calls) out of synchronous web requests.
Size PHP-FPM workers and memory from evidence, not guesswork - see Performance tuning.

When to contact support

If the host stays unhealthy after the steps above, or PHP-FPM keeps crashing for no clear reason, contact Support. Include the host and domain, the exact error code, what changed recently (a publish or deploy), and the relevant log excerpt.