Debugging Gateway Errors

Published on by

You'll sometimes hit Gateways errors, usually 502 Bad Gateway or 504 Gateway Timeout.

These are errors Nginx returns when it sends a request to PHP but PHP is returning some error saying it can't process the request. Typically these are NOT errors occuring in your application, but instead are (usually) errors hit before the application even processes a request.

What is Gateway

A Gateway is a thing sitting between the web server (usually Nginx) and your application. For most of us, this is PHP-FPM. Nginx will use the fastcgi protocol to convert a web request into something PHP-FPM can understand. PHP-FPM then runs your application, setting up PHP with the information it needs (setting superglobals $_GET, $_POST, $_SESSION, $_SERVER, etc).

If PHP-FPM returns and error, Nginx gives us a Gateway error.

Bad Gateway

Bad Gateway is returned when PHP-FPM returns an error. This usually is one of:

  1. PHP-FPM is not running (perhaps due to too many error)
  2. PHP-FPM has reached it's max_children limit and cannot process any more requests
  3. Some sort of PHP error such as a segfault

Gateway Timeout

Gateway timeout errors typically occur when your app is handling too much traffic. This can correspond to PHP-FPM max_children errors (too many requests that it's configured to handle) but mostly occurs when your database is overloaded and it can't handle additional connections making queries. It takes too much time to return queries.

This can also occur if any network connection your application makes is not returning responses in time, but the database is the most common bottleneck.

Debugging Gateway Errors

The tl;dr for debugging gateway errors is the logs. I start from the top of the network request stack, and move down. This means the order of logs I check are:

  1. Nginx
  2. PHP-FPM
  3. Server resource usage
  4. Application logs

The Nginx logs typically have the least useful data, altho it might clue you into issues of PHP-FPM not running (if it can't find PHP-FPM's socket file such as /var/run/php-fpm.sock for example).

The FPM logs are usually the most beneficial, since PHP-FPM is the gateway returning an error! Often you'll see an error about hitting (or being close to) the max_children limit. Less often you might see a setfault error (if you see that, you probably have some recursion in your code somewhere).

Server resource usage is what I'd check next. You can use htop or similar to check CPU/RAM usage, and what processes are using them. You should also check disk usage via df -h to check if the disk is out of space.

You may also run out of inodes! Inodes are "index nodes", things used to track file usage on linux systems. Since everything is a file (including how Linux handles open network connections!) running out of inodes can be an issue. You can run df -i to see inode usage per disk drive.

Finally I check application logs. These MIGHT show errors related to timeouts of or database errors, but sometimes the issue is not specific to the application code base. How useful these logs are will vary for Gateway errors.

Chris Fidao photo

Teaching coding and servers at CloudCasts and Servers for Hackers. Co-founder of Chipper CI.

Cube

Laravel Newsletter

Join 40k+ other developers and never miss out on new tips, tutorials, and more.

image
Honeybadger

Fix Laravel errors in record time. Fill in the gaps with uptime, cron, and heartbeat monitoring. Build trust with status pages and incident management—all in one simple platform.

Visit Honeybadger

The latest

View all →
Use Ollama LLM Models Locally with Laravel image

Use Ollama LLM Models Locally with Laravel

Read article
TallStackUI - a new component library for TALL Stack apps image

TallStackUI - a new component library for TALL Stack apps

Read article
Laravel 10.34 Released image

Laravel 10.34 Released

Read article
Laravel Tailwind Merge image

Laravel Tailwind Merge

Read article
Generate Validation Rules from a Database Schema in Laravel image

Generate Validation Rules from a Database Schema in Laravel

Read article
A Feature Flags Implementation for Filament image

A Feature Flags Implementation for Filament

Read article
Honeybadger logo

Honeybadger

Zero-instrumentation, 360 degree coverage of errors, outages and service degradation.

Honeybadger
Laravel Forge logo

Laravel Forge

Easily create and manage your servers and deploy your Laravel applications in seconds.

Laravel Forge
Oh Dear logo

Oh Dear

Oh Dear is the best all-in-one monitoring tool for all your Laravel apps.

Oh Dear
Tinkerwell logo

Tinkerwell

The must-have code runner for Laravel developers. Tinker with AI, autocompletion and instant feedback on local and production environments.

Tinkerwell
Kirschbaum logo

Kirschbaum

Providing innovation and stability to ensure your web application succeeds.

Kirschbaum
Shift logo

Shift

Running an old Laravel version? Instant, automated Laravel upgrades and code modernization to keep your applications fresh.

Shift
Bacancy logo

Bacancy

Supercharge your project with a seasoned Laravel developer with 4-6 years of experience for just $2500/month. Get 160 hours of dedicated expertise & a risk-free 15-day trial. Schedule a call now!

Bacancy
LoadForge logo

LoadForge

Easy, affordable load testing and stress tests for websites, APIs and databases.

LoadForge
Paragraph logo

Paragraph

Manage your Laravel app as if it was a CMS – edit any text on any page or in any email without touching Blade or language files.

Paragraph
Lucky Media logo

Lucky Media

Bespoke software solutions built for your business. Partner with Lucky Media, your favorite Laravel Development Agency!

Lucky Media
Lunar: Laravel E-Commerce logo

Lunar: Laravel E-Commerce

E-Commerce for Laravel. An open-source package that brings the power of modern headless e-commerce functionality to Laravel.

Lunar: Laravel E-Commerce