Outsource Laravel Development Partner - $2500/Month | Bacancy

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
Curotec

Curotec helps software teams hire the best Laravel developers in Latin America. Click for rates and to learn more about how it works.

Visit Curotec
Curotec logo

Curotec

World class Laravel experts with GenAI dev skills. LATAM-based, embedded engineers that ship fast, communicate clearly, and elevate your product. No bloat, no BS.

Curotec
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
Laravel Forge logo

Laravel Forge

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

Laravel Forge
Tinkerwell logo

Tinkerwell

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

Tinkerwell
Cut PHP Code Review Time & Bugs into Half with CodeRabbit logo

Cut PHP Code Review Time & Bugs into Half with CodeRabbit

CodeRabbit is an AI-powered code review tool that specializes in PHP and Laravel, running PHPStan and offering automated PR analysis, security checks, and custom review features while remaining free for open-source projects.

Cut PHP Code Review Time & Bugs into Half with CodeRabbit
Join the Mastering Laravel community logo

Join the Mastering Laravel community

Connect with experienced developers in a friendly, noise-free environment. Get insights, share ideas, and find support for your coding challenges. Join us today and elevate your Laravel skills!

Join the Mastering Laravel community
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
Lucky Media logo

Lucky Media

Get Lucky Now - the ideal choice for Laravel Development, with over a decade of experience!

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
LaraJobs logo

LaraJobs

The official Laravel job board

LaraJobs
SaaSykit: Laravel SaaS Starter Kit logo

SaaSykit: Laravel SaaS Starter Kit

SaaSykit is a Multi-tenant Laravel SaaS Starter Kit that comes with all features required to run a modern SaaS. Payments, Beautiful Checkout, Admin Panel, User dashboard, Auth, Ready Components, Stats, Blog, Docs and more.

SaaSykit: Laravel SaaS Starter Kit

The latest

View all →
Streamline Conditional Logic with Laravel's Fluent Conditionable Trait image

Streamline Conditional Logic with Laravel's Fluent Conditionable Trait

Read article
Sublime Text Releases Update With Support for Right Sidebar image

Sublime Text Releases Update With Support for Right Sidebar

Read article
Enhance Email Validation with Laravel's Fluent Email Rule Object image

Enhance Email Validation with Laravel's Fluent Email Rule Object

Read article
Locale-aware Number Parsing in Laravel 12.15 image

Locale-aware Number Parsing in Laravel 12.15

Read article
Handle Fluent Values as Arrays with Laravel's array() Method image

Handle Fluent Values as Arrays with Laravel's array() Method

Read article
Chargebee Starter Kit for Billing in Laravel image

Chargebee Starter Kit for Billing in Laravel

Read article