PHP-FPM Errors

Diagnose and fix common PHP-FPM issues, 502 Bad Gateway, pool exhaustion, slow responses, and configuration errors

PHP-FPM (FastCGI Process Manager) errors typically manifest as 502 Bad Gateway in Nginx or blank white pages. This guide covers the most common causes and fixes.

Step 1: Check the logs

Always start here:

# PHP-FPM error log
sudo tail -50 /var/log/php8.2-fpm.log
# (adjust version: php7.4-fpm.log, php8.1-fpm.log, etc.)

# Nginx error log (for 502 errors)
sudo tail -50 /var/log/nginx/error.log

# PHP-FPM pool-specific log
sudo tail -50 /var/log/php8.2-fpm/www-error.log

Error 1: 502 Bad Gateway (PHP-FPM not running)

connect() to unix:/run/php/php8.2-fpm.sock failed (2: No such file or directory)

PHP-FPM is not running or the socket doesn't exist:

sudo systemctl status php8.2-fpm
sudo systemctl start php8.2-fpm
sudo systemctl enable php8.2-fpm

If it fails to start, check the config:

sudo php-fpm8.2 -t

Error 2: Pool exhausted (too many requests)

WARNING: [pool www] seems busy (you may need to increase pm.max_children)

The worker pool is full, all PHP processes are busy. Fix by increasing pool size:

sudo nano /etc/php/8.2/fpm/pool.d/www.conf

Adjust these values based on your RAM (each PHP worker uses ~30-60 MB):

; Process manager
pm = dynamic

; Maximum number of child processes
pm.max_children = 20

; Number of processes to start at boot
pm.start_servers = 5

; Minimum idle processes
pm.min_spare_servers = 3

; Maximum idle processes
pm.max_spare_servers = 8

; Kill workers after this many requests (prevents memory leaks)
pm.max_requests = 500

Quick formula:

pm.max_children = Available RAM for PHP / Average PHP process RAM
# Example: 2048 MB / 50 MB = 40 max_children

Check current PHP process memory usage:

ps -o pid,rss,command -C php-fpm8.2 | awk '{print $1, $2/1024 " MB", $3}'

Apply:

sudo systemctl reload php8.2-fpm

Error 3: PHP timeout (504 Gateway Timeout)

ERROR: pool www child timed out after X seconds

PHP script is taking too long. Increase timeouts:

In /etc/php/8.2/fpm/pool.d/www.conf:

request_terminate_timeout = 120

In /etc/php/8.2/fpm/php.ini:

max_execution_time = 120
max_input_time = 120

In Nginx config:

location ~ \.php$ {
    fastcgi_read_timeout 120;
    fastcgi_send_timeout 120;
    # ... rest of config
}

Apply all three:

sudo systemctl reload php8.2-fpm
sudo systemctl reload nginx

Error 4: Permission denied on socket

connect() to unix:/run/php/php8.2-fpm.sock failed (13: Permission denied)

Nginx user (www-data) doesn't have access to the PHP-FPM socket. Fix socket permissions:

In /etc/php/8.2/fpm/pool.d/www.conf:

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

Apply:

sudo systemctl restart php8.2-fpm

Error 5: Out of memory (PHP fatal error)

PHP Fatal error: Allowed memory size of 134217728 bytes exhausted

Increase PHP memory limit:

sudo nano /etc/php/8.2/fpm/php.ini

memory_limit = 512M

Or per-virtualhost in Nginx:

location ~ \.php$ {
    fastcgi_param PHP_VALUE "memory_limit=512M";
    include fastcgi_params;
    fastcgi_pass unix:/run/php/php8.2-fpm.sock;
}

Error 6: Opcache issues (blank page after code update)

PHP shows old code because Opcache hasn't flushed:

# Clear Opcache
sudo systemctl reload php8.2-fpm

Or via PHP script (if you can access the server):

<?php opcache_reset(); ?>

Enable Opcache revalidation in /etc/php/8.2/fpm/php.ini (slower but avoids stale cache):

opcache.validate_timestamps = 1
opcache.revalidate_freq = 2

For production, disable revalidation and clear manually on deploy:

opcache.validate_timestamps = 0

Error 7: PHP-FPM config syntax error

ERROR: failed to open configuration file '/etc/php/8.2/fpm/pool.d/www.conf'

Test the config before restarting:

sudo php-fpm8.2 --test
# or
sudo php-fpm8.2 -t

Monitor PHP-FPM in real time

Enable the status page in /etc/php/8.2/fpm/pool.d/www.conf:

pm.status_path = /fpm-status

In Nginx:

location /fpm-status {
    allow 127.0.0.1;
    deny all;
    fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}

Check status:

curl http://127.0.0.1/fpm-status

Output shows active processes, idle processes, request queue, and slow requests.

Quick reference

Symptom	Likely cause	Fix
`502 Bad Gateway`	PHP-FPM not running	`systemctl start php-fpm`
`502` + socket error	Wrong socket path in Nginx	Match `fastcgi_pass` to actual socket
`504 Timeout`	Script too slow	Increase `request_terminate_timeout`
`Permission denied`	Socket ownership	Set `listen.owner = www-data`
Blank page	Fatal PHP error	Check `/var/log/php-fpm.log`
Old code showing	Opcache stale	`systemctl reload php-fpm`
High load	Pool exhausted	Increase `pm.max_children`

On this page