Fix a 502 Bad Gateway on your site

A 502 Bad Gateway page comes from Nginx, the web server in front of your application. It means Nginx is running and received the request, but the program behind it (PHP-FPM for a PHP site, the Node.js process for a Next.js or Nuxt site) did not answer properly. Your visitors see an error page, while the server and SrvYard are usually fine.

This article gives you the shortest route from the error to the cause: confirm which site and which server, check the services, check that the site's PHP version exists, read the log that names the failed connection, restart the right thing, and deal with the causes that appear right after a deployment.

Before you begin#

• Which site shows the error, and since when? If every site on the server fails, the cause is on the server. If only one fails, look at that site first.
• Rights. Viewing services, runtimes and logs needs view access to the server and site; restarting a service needs servers:manage-services. See Roles and permissions.
• What changed just before. A deployment, a PHP version change, a package update or a reboot is the cause far more often than a random failure. Check the Deployments and Activity tabs.

1. Check that the services are running#

Open the server, then Services.

1. PHP-FPM. One row for each installed PHP version, named php8.4-fpm and so on. This is the program a PHP site hands requests to. A site on PHP 8.4 needs the 8.4 row to be running.
2. Nginx. The web server that shows the 502. If this one is stopped you would get a connection error rather than a 502, but a broken configuration can leave it half working.
3. Status. Running is healthy. Anything else on a service your site depends on is your lead.

If a service is not running, open the actions menu at the end of its row.

1. Restart. Stops and starts the service. For PHP-FPM this clears stuck workers and picks up a changed configuration. Restarting asks for confirmation first, and a restart drops requests that are in flight.
2. Reload. A graceful reload: workers finish their requests first. Use it after a configuration change when you can.
3. View logs. Shows the log of that service, which says why it stopped.

2. Check the site's PHP version exists#

A site is tied to one PHP version, and Nginx hands its requests to the PHP-FPM pool of that version. If that version was removed from the server, or its PHP-FPM is not running, the site answers 502.

Open Runtimes on the server.

1. PHP-FPM. Running for every version a site uses.
2. Sites. How many sites use each version. A version with sites on it must stay installed and running.

Then open the site, Settings, and look at the PHP version card.

1. PHP version. The card explains that switching creates a new pool, points Nginx at it and removes the old one, and that only versions installed on the server are listed.
2. Change PHP version. Applies the selected version. Use it to move the site to a version that runs.

If the right version is missing on the server, install it from Runtimes first. See Choose and switch PHP versions.

3. Read the Nginx error log#

Services tell you what is running; the log tells you what failed. Open the site, then Logs.

1. Log. Choose Nginx error log. The list also has the Nginx access log, the PHP error log for PHP sites and the Laravel log for Laravel-based sites.
2. Lines. How many of the latest lines to show.
3. Refresh. Reads the log again.
4. Auto-refresh. Keeps reading while you reload the failing page in another tab, so the new line appears at once.

Look for the line with the time of your request. The messages Nginx writes for a 502 are standard, so they are easy to search for:

4. Restart what runs your application#

• A PHP site: restart or reload PHP-FPM (step 1). With OPcache set for production, PHP-FPM must also be reloaded after a deployment that does not switch releases, as the Runtimes settings point out.
• A Next.js or Nuxt site in server mode: the site's Node.js process is managed by Supervisor. Check it under Processes for the site or Daemons for the server, and restart it there. If it keeps stopping, its start command or port is wrong, or it ran out of memory.
• A Laravel site on Octane or Horizon: the long-running processes must be restarted after each deployment. SrvYard's default deploy script does this with $RESTART_QUEUES(); a custom script must do the same. See The Laravel panel.

5. The 502 started right after a deployment#

When the first 502 comes minutes after a deploy, assume the new release is broken:

1. Roll back to the last good deployment (Deployments, the actions menu of that row, Roll back to this) to restore service. See Zero-downtime releases and rollbacks.
2. Read the deployment output and the application log for the first error. See Find out why a deployment failed and fix it.
3. Typical causes: a new composer.json that needs a PHP version the site does not run, a missing PHP extension, a changed .env value, a migration that broke a query, or a build that ran out of memory.

The release check in the site settings (Health checks) catches this for you: a failing check marks the deployment as failed so you notice at once.

Troubleshooting#

• The 502 appears only now and then. PHP-FPM workers are being exhausted or killed. Check memory on the server's Monitoring tab and the PHP error log. See Disk full, out of memory or a slow server.
• Restarting PHP-FPM fixed it for an hour. The cause is still there. Read the PHP error log around the time it failed, and look for memory limits and long requests.
• Only large uploads or reports fail. That is usually a time or size limit. In Runtimes, the global settings include the maximum upload size and the maximum execution time.
• The error page is not from my application. A 502 page with the Nginx name comes from Nginx. If you see a Cloudflare error instead, check your origin server, the SSL mode and the DNS record in Cloudflare.
• After switching the PHP version, the site is down. The new version's PHP-FPM is not running or the extensions your code needs are missing. Switch back and install what is needed first. See PHP extensions and php.ini settings.
• All sites on the server fail. Check Nginx and PHP-FPM on Services, then memory and disk on Monitoring.

Related#

• Find out why a deployment failed and fix it: when the 502 follows a deploy.
• Manage services and restarts: what each service does.
• Choose and switch PHP versions: installing and changing versions.
• Read site logs and run commands: the logs in more detail.