$ guides / php-fpm / php-fpm-request-terminate-timeout ▌

Operations Guides

PHP-FPM request_terminate_timeout: stopping stuck requests from eroding the pool

PHP-FPM pools silently lose capacity when workers get stuck and never return to idle. The default request_terminate_timeout = 0 means a single deadlocked request, infinite loop, or hung database call occupies a worker forever. Over time, these stuck workers accumulate. The pool keeps running, requests keep being accepted, but effective concurrency shrinks with no error and no alert.

The symptom is subtle. Stuck workers are still counted as active in the FPM status page, so the count looks normal. In static mode, active processes sits at pm.max_children with idle processes at 0, but throughput is lower than the traffic should produce. The web server does not complain. The full status page reveals workers with request durations far exceeding your baseline. Eventually a traffic spike hits the reduced effective pool, the listen queue fills, and users see 502s. By the time the outage is visible, capacity has been eroding for hours or days.

The fix is a single directive: set request_terminate_timeout to a positive value (30 to 60 seconds for most web applications). This gives the FPM master a hard kill switch. When a worker exceeds the timeout, the master sends SIGTERM, logs the termination, and spawns a replacement. The stuck worker is reclaimed, effective capacity restored.

What this means

request_terminate_timeout is a pool-level directive in your pool configuration file (typically /etc/php/*/fpm/pool.d/www.conf). It is commented out by default, and the default value of 0 disables the timeout entirely.

When set to a positive value, the FPM master process tracks wall-clock time for each request. If a worker exceeds the threshold, the master sends SIGTERM to kill the worker. The error log records the event with a two-line pattern:

WARNING: [pool www] child N, script '/path/to/script.php' execution timed out (30.000000 sec), terminating
WARNING: [pool www] child N exited on signal 15 (SIGTERM) after 30.000000 seconds from start

The critical distinction is wall-clock time. This counts everything: CPU computation, I/O waits, database queries, external API calls, sleep(), NFS stalls. It is the only reliable safeguard against stuck requests in PHP-FPM.

PHP’s max_execution_time is not a substitute. On Linux, max_execution_time measures CPU time only (implemented via setitimer(ITIMER_PROF)). A script that calls sleep(300), waits on a hung database query, or polls a dead API endpoint consumes zero CPU during the wait and never triggers max_execution_time.

request_terminate_timeout is the only built-in wall-clock kill switch PHP-FPM has.

flowchart TD
    A[Request arrives] --> B[Worker picks up request]
    B --> C{Request completes?}
    C -->|Yes| D[Worker returns to idle]
    C -->|No - hung or looping| E[Worker stuck indefinitely]
    E --> F{request_terminate_timeout set?}
    F -->|0 = disabled| G[Worker stuck permanently, effective capacity erodes]
    F -->|> 0| H[SIGTERM after timeout]
    H --> I[Worker killed and logged]
    I --> J[Master spawns replacement]

Common causes

Cause	What it looks like	First thing to check
Deadlocked database connection	Worker runs for minutes, low CPU, no response	Slow log stack trace showing PDO or mysqli calls
Infinite loop in application code	Worker pegged at 100% CPU, request never completes	Per-worker CPU in full status, slow log
Hung external API call	Worker blocked on network I/O, cURL or stream functions in stack trace	Slow log, test the external service independently
NFS or filesystem stall	Multiple workers stuck on file operations simultaneously	`dmesg` for NFS errors, check mount health
Session lock contention	Workers serialized on same session ID, AJAX-heavy pages	Slow log showing `session_start()`, `lsof` on session files

Quick checks

# Check if request_terminate_timeout is set (0 = disabled, the dangerous default)
php-fpm -tt 2>&1 | grep request_terminate_timeout

# Check active and idle counts (path depends on your nginx config for the status page)
curl -s http://127.0.0.1/fpm-status | grep -E "active|idle|total"

# Find stuck workers by duration (full status shows per-worker request duration in microseconds)
curl -s 'http://127.0.0.1/fpm-status?full' | grep "request duration" | sort -t: -k2 -rn | head

# Check for SIGTERM kills in the error log (path varies by distribution and PHP version)
grep "exited on signal 15" /var/log/php-fpm/error.log | tail -20

# Check the full terminate log pattern
grep "execution timed out" /var/log/php-fpm/error.log | tail -20

# Compare timeouts across the request path
php-fpm -tt 2>&1 | grep request_terminate_timeout
php -i 2>/dev/null | grep max_execution_time
nginx -T 2>&1 | grep -E "fastcgi_read_timeout|fastcgi_send_timeout"

How to diagnose it

Confirm workers are stuck, not just busy. Stuck workers still count as active in the FPM status page. In static mode, look for active processes at pm.max_children with idle processes at 0, combined with throughput that does not match the traffic level. The pool reports as fully utilized, but effective capacity is reduced. The full status page is where the real evidence lives.
Identify stuck workers. Fetch the full status page and sort by request duration. The value is in microseconds. Any worker running 10x or more beyond your p95 baseline is stuck or about to be. Note the script and request URI fields to identify which endpoint is the culprit.
Check the error log for terminate kills. If request_terminate_timeout is already set, look for the two-line pattern: execution timed out, terminating followed by exited on signal 15 (SIGTERM). These confirm the timeout is firing. A sustained rate of these entries means something upstream is consistently hanging.
Verify the slow log is enabled. If request_slowlog_timeout is 0 (disabled), you have no visibility into where workers are blocking. Enable it at 5 seconds so the next stuck request leaves a stack trace before the hard timeout fires.
Check nginx timeout alignment. If fastcgi_read_timeout is shorter than request_terminate_timeout, nginx gives up first (returning 504 to the user) while the FPM worker continues processing a response nobody will receive. These phantom workers waste capacity until the terminate timeout eventually kills them.

Metrics and signals to monitor

Signal	Why it matters	Warning sign
Active processes at max_children, idle at 0	Pool reports as saturated but some workers may be stuck, not productive	Throughput far below expected for current traffic level
Per-worker request duration (full status)	Identifies individual stuck workers before they drain effective capacity	Any worker at 10x or more beyond p95 baseline
Worker exits on signal 15 (SIGTERM)	Confirms request_terminate_timeout is firing	Sustained rate of SIGTERM exits during normal traffic
Slow log entry rate	Shows where workers block, before the hard timeout	New entries for endpoints that were previously fast
Accepted connections vs completed throughput	High acceptance with low completion means workers are stuck	Divergence between these two rates

Fixes

Set request_terminate_timeout

In your pool configuration, uncomment and set the directive:

request_terminate_timeout = 30

This sets a 30-second hard kill. Adjust based on your application’s legitimate long-running endpoints. If you have a background job runner or import script served through FPM, set the timeout high enough to accommodate it, or move that work out of the web request path entirely.

Apply with a graceful reload. SIGUSR2 re-execs the master, which re-reads config. Existing workers continue serving in-flight requests during the transition; new connections queue briefly in the listen backlog until the new master spawns workers.

# Graceful reload via SIGUSR2
kill -USR2 $(cat /run/php-fpm.pid)
# Or via systemd (service name varies: php-fpm, php8.2-fpm, etc.)
systemctl reload php-fpm

Enable request_terminate_timeout_track_finished (PHP 7.3+)

If your application uses fastcgi_finish_request() to flush the response early and continue processing in the background, the default behavior stops tracking wall-clock time after the response is sent. Code running post-finish can occupy a worker indefinitely. Set:

request_terminate_timeout_track_finished = yes

This keeps the wall-clock timer running even after fastcgi_finish_request() is called or during shutdown function execution.

Align nginx timeouts

The shortest timeout in the request path wins. This determines whether the user sees a 502 (FPM killed first, connection closed) or a 504 (nginx gave up first, FPM worker continues as a phantom).

Scenario	nginx fastcgi_read_timeout	FPM request_terminate_timeout	Effect
FPM kills first	60s	30s	Worker freed cleanly, user sees 502
nginx kills first	30s	60s	User sees 504, FPM worker continues as phantom until FPM timeout
Aligned	60s	55s	FPM kills just before nginx gives up, minimal phantom window

The recommended pattern is to set request_terminate_timeout slightly below fastcgi_read_timeout. This ensures FPM kills stuck workers before nginx abandons the request, preventing phantom workers from consuming capacity. The user still sees an error (502 from the closed connection), but the pool stays healthy.

Avoid request_terminate_timeout with APCu contention paths

If request_terminate_timeout kills a worker mid-operation on APCu (for example during apcu_store), the APCu spinlock mutex may never release. Subsequent workers accessing the same cache key deadlock. If you rely on APCu for hot path caching, test whether your workload triggers the contention path before enabling the timeout.

Prevention

Set request_terminate_timeout on every production pool. 30 to 60 seconds covers most web requests. The cost is one SIGTERM per stuck request. The benefit is preventing permanent capacity erosion from stuck workers.
Set request_slowlog_timeout alongside it. The slow log fires before the hard timeout, giving you stack traces that explain why workers are sticking. Without it, the terminate kill tells you that something hung, but not what.
Monitor throughput against worker utilization. If active processes sits at max_children with 0 idle but throughput is lower than expected for the traffic level, some workers are likely stuck. The full status page confirms it with extreme request durations.
Move long-running work out of FPM. Background jobs, imports, report generation, and queue workers should run in a separate process (cron, systemd service, queue worker), not in an FPM worker. If you must serve long requests through FPM, use a dedicated pool with a higher timeout.
Keep timeout chains coherent. nginx fastcgi_read_timeout, PHP max_execution_time, and FPM request_terminate_timeout should be layered deliberately. The goal is no surprises: the user-facing timeout should fire after the application-level safeguards have had their chance.

How Netdata helps

Per-second polling of FPM pool metrics catches the divergence between worker count and throughput that indicates stuck workers. At 1-second resolution, you see the exact moment active processes max out while accepted connections keep climbing but completed requests stall.
Correlating FPM pool saturation with nginx upstream errors reveals timeout mismatches. If nginx 504s spike while FPM active processes stay elevated, the nginx timeout is firing before the FPM kill, creating phantom workers.

Alerting on pool utilization thresholds detects capacity erosion before users see errors. An alert on sustained 0 idle processes with declining throughput is an early warning that stuck workers are reducing effective capacity.