Learn how to fix 504 Gateway Timeout errors in PHP-FPM using proven Nginx and Apache configurations, timeout tuning, and performance diagnostics for production servers.
A 504 Gateway Timeout occurs when the web server (usually Nginx or Apache) waits too long for a response from PHP-FPM and eventually gives up. This is not a browser issue. This is not a DNS issue. This is a backend execution and resource coordination problem.
When handled correctly, the fix is deterministic.
Below is the exact order we follow in production environments.
Prerequisites
Before we begin, let’s ensure we have the following in place:
- A Linux OS installed on dedicated server or KVM VPS.
- A basic programming knowledge.
Learn how to fix 504 Gateway Timeout errors in PHP-FPM
Step 1: Confirm the Error Source Is PHP-FPM
Before touching configurations, confirm the timeout originates between the web server and PHP-FPM.
Check web server error logs:
# Nginx
tail -f /var/log/nginx/error.log
# Apache
tail -f /var/log/apache2/error.log
Typical indicators include:
- upstream timed out
- FastCGI sent in stderr
- connection timed out while reading response header from upstream
If these messages exist, the gateway timeout is confirmed as a PHP-FPM execution delay, not a networking issue.
Step 2: Inspect PHP-FPM Logs Immediately
PHP-FPM logs reveal whether requests are slow, blocked, or crashing.
tail -f /var/log/php*-fpm.log
Common red flags:
- server reached pm.max_children
- request terminated
- child exited with code
If these appear, PHP-FPM is overloaded or misconfigured. No tuning, no fix.
Step 3: Increase PHP-FPM Execution Time Safely
Long-running scripts are the most common cause of 504 errors.
Edit php.ini:
max_execution_time = 300
max_input_time = 300
memory_limit = 512M
Restart PHP-FPM:
systemctl restart php-fpm
This does not solve bad code, but it prevents premature termination while deeper issues are addressed.
Step 4: Align Web Server Timeouts With PHP-FPM
A mismatch between PHP-FPM and web server timeouts guarantees failure.
For Nginx
fastcgi_read_timeout 300;
fastcgi_connect_timeout 300;
fastcgi_send_timeout 300;
Reload Nginx:
nginx -t && systemctl reload nginx
For Apache (Proxy + PHP-FPM)
ProxyTimeout 300
Restart Apache afterward.
Timeout symmetry matters. One side expiring earlier breaks the request chain.
Step 5: Fix PHP-FPM Pool Configuration (Critical)
Most production 504 errors are caused by undersized PHP-FPM pools.
Edit pool config:
pm = dynamic
pm.max_children = 30
pm.start_servers = 5
pm.min_spare_servers = 5
pm.max_spare_servers = 10
request_terminate_timeout = 300
Guideline:
- pm.max_children must match available RAM
- Each PHP process typically consumes 30–60 MB
Restart PHP-FPM after changes.
If pm.max_children is too low, requests queue until timeout.
Step 6: Check Server Resource Exhaustion
504 errors often surface when CPU, RAM, or disk I/O is saturated.
Run:
top
free -m
df -h
Watch for:
- High load average
- Swap usage
- Disk at 100%
If resources are exhausted, configuration tuning will not save the system. Capacity must increase or workload must decrease.
Step 7: Identify Slow PHP Code or Queries
Timeouts are symptoms. Slow execution is the disease.
Enable slow log in PHP-FPM:
slowlog = /var/log/php-fpm-slow.log
request_slowlog_timeout = 10s
Restart PHP-FPM and observe logged scripts.
If database queries are involved:
- Missing indexes
- Large table scans
- External API calls without timeouts
No amount of server tuning compensates for inefficient logic.
Step 8: Verify Database Response Time
A slow database makes PHP appear slow.
Test query response:
mysqladmin processlist
Look for:
- Locked queries
- Long-running selects
- Too many concurrent connections
If database latency exists, the fix belongs there, not in PHP-FPM.
Step 9: Validate Reverse Proxy or Load Balancer Settings
If a load balancer exists, its timeout must exceed backend timeouts.
Common issue:
Load balancer timeout = 60s
PHP execution = 120s
Result: consistent 504 errors despite “correct” server configs.
Step 10: Restart Services in Correct Order
After changes, restart in dependency order:
systemctl restart php-fpm
systemctl restart nginx
# or
systemctl restart apache2
Validate logs again. No errors should appear under normal load.
Final Notes
A 504 Gateway Timeout in PHP-FPM is never random. It is always caused by one of the following:
- Timeout mismatch
- PHP-FPM pool exhaustion
- Resource limits
- Slow code or database latency
When we address these systematically, the error disappears and stays gone.
This approach is stable, scalable, and aligned with modern production environments.
