PHP-FPM OPcache thrashing: a full cache recompiling PHP on every request

Every PHP request is suddenly slow. Latency is up across every endpoint, not just one. CPU is pinned across every worker, not a subset. The PHP-FPM status page shows workers running, the listen queue may be empty, and pm.max_children is not the binding constraint. A graceful reload helps for a minute, then the slowness returns. You are probably inside an OPcache thrash.

OPcache is the shared memory segment every worker in a PHP-FPM pool reads precompiled bytecode from. When the segment fills, OPcache evicts scripts still in use, recompiles them on the next request, and evicts other scripts to make room. The result is a continuous evict/compile cycle: each request landing on an uncached script pays the full parse and compile cost inside the worker.

The signature that separates this from a slow dependency is uniformity. All workers burn CPU, all endpoints slow down, and nothing on the FPM status page explains it. The diagnostic lives in opcache_get_status(), not in the pool scoreboard. The fix is to give OPcache more memory (opcache.memory_consumption) or more script slots (opcache.max_accelerated_files), depending on which limit is actually binding.

What this means

OPcache is one mmap(MAP_SHARED) segment per pool. All workers in the pool read from the same compiled bytecode. A hit serves cached opcode directly. A miss forces PHP to open the source, parse it, compile it to opcode, write the result into the shared segment, then run it. Compilation is CPU work performed inside the worker that served the request.

When the shared segment is full and a new script needs to be cached, OPcache must make room. The full restart that reclaims wasted memory only fires when wasted memory crosses opcache.max_wasted_percentage (default 5%). If wasted memory stays below that threshold, the cache sits full, never restarts, and the only path is constant churn: evict a script, compile the new one, evict another, compile another. The cache_full, restart_pending, and restart_in_progress fields from opcache_get_status() describe this state directly.

The downstream effect is uniform CPU saturation and uniform latency. Compilation happens inside the worker, so every worker that hits a miss is busy. Misses are spread across the whole codebase, so every endpoint is slow, not just a hot one. Reloads do not help: a freshly emptied OPcache warms back to full within minutes and starts thrashing again, because the underlying constraint (too little memory or too few slots) is unchanged.

flowchart TD
    A[OPcache segment fills] --> B[New script needs space]
    B --> C{Wasted pct > max_wasted_percentage?}
    C -- No --> D[Evict in-use script, cache new one]
    D --> E[Next request recompiles evicted script]
    E --> B
    C -- Yes --> F[Full restart, cache empties]
    F --> G[Workers recompile everything on next request]
    G --> H[Cache refills, returns to A]

Common causes

The default opcache.memory_consumption of 128 MB and opcache.max_accelerated_files of 10000 are conservative. Either can become the binding constraint before the other. opcache.max_accelerated_files is rounded up to the next prime in a fixed internal set, so the effective value will be a prime at least as large as what you set.

Quick checks

All checks below are read-only and do not touch the running pool. Serve a small PHP script through FPM (the only OPcache you actually care about), since CLI PHP uses a separate OPcache (or none, given opcache.enable_cli=0 by default).

# Drop this script somewhere served by FPM, e.g. opcache-status.php:
#   <?php header('Content-Type: application/json'); echo json_encode(opcache_get_status(false));
# WARNING: protect this endpoint (IP allowlist or basic auth). It leaks file paths, script counts, and version info.

# Hit rate, miss and restart counters, memory state, restart flags
curl -s http://127.0.0.1/opcache-status.php | python3 -c "
import sys, json
s = json.load(sys.stdin); st = s['opcache_statistics']; m = s['memory_usage']
print(f\"hit_rate={st['opcache_hit_rate']:.2f}% hits={st['hits']} misses={st['misses']}\")
print(f\"oom_restarts={st['oom_restarts']} hash_restarts={st['hash_restarts']} num_cached_scripts={st['num_cached_scripts']}\")
print(f\"used={m['used_memory']/1048576:.1f}MB free={m['free_memory']/1048576:.1f}MB wasted={m['wasted_memory']/1048576:.1f}MB\")
print(f\"cache_full={s['cache_full']} restart_pending={s['restart_pending']} restart_in_progress={s['restart_in_progress']}\")"

# Interned strings buffer (allocated inside memory_consumption, not on top of it)
curl -s http://127.0.0.1/opcache-status.php | python3 -c "
import sys, json
i = json.load(sys.stdin)['interned_strings_usage']
print(f\"buffer={i['buffer_size']/1048576:.1f}MB used={i['used_memory']/1048576:.1f}MB free={i['free_memory']/1048576:.1f}MB strings={i['number_of_strings']}\")"

# Count PHP files the application can compile
find /path/to/app -name '*.php' | wc -l

# Per-worker CPU (uniform high CPU distinguishes thrash from a slow dependency)
ps -C php-fpm -o pid,pcpu,rss,args --sort=-pcpu | head

To inspect the running PHP’s effective directives (memory_consumption, max_accelerated_files, validate_timestamps, revalidate_freq), extend the same script with ini_get() calls rather than reading php.ini from disk. FPM pool config and admin values can override file defaults.

How to diagnose it

1. Confirm the hit rate has fallen. After warmup (the first 5-10 minutes after restart or deploy), opcache_statistics.opcache_hit_rate should be above 99%. Anything below 95% sustained, with active traffic, is a problem.
2. Confirm the binding constraint. Open opcache_get_status() and compare against the table above. The fix branches on which limit is hit.
3. Confirm the restart state. cache_full=true with restart_pending=false and restart_in_progress=false is the textbook thrash state: the cache is full but PHP will not restart it because wasted memory is below the threshold. Non-zero oom_restarts confirms OPcache has been forcefully cleared at least once.
4. Rule out a cold start. A low hit rate in the first few minutes after a restart or deploy is expected warmup, not thrash. The signal that turns warmup into thrash is that the hit rate never recovers as traffic continues.
5. Rule out a slow dependency. Slow-dependency worker drain shows low CPU (workers blocked on I/O) and concentrates on specific endpoints. OPcache thrash shows high CPU on all workers and slowness on every endpoint.
6. Check the deploy pattern. If you ship a new release directory per deploy and flip a symlink to it, OPcache has been caching the same scripts under N different paths, one per release. Old paths are never invalidated because nothing loads them anymore, so wasted_memory stays low and the cache never reaches the restart threshold.

Metrics and signals to monitor

The FPM status page will not surface any of these. OPcache instrumentation must be collected from opcache_get_status() and tracked as its own signal source, not rolled into the FPM status poll.

Fixes

If memory is the binding constraint

Raise opcache.memory_consumption. The default is 128 MB; many framework-heavy applications need 256 MB or more.

opcache.memory_consumption=256

Changing opcache.memory_consumption requires rebuilding the FPM process tree because the shared segment is sized at master startup. The upstream systemd template maps reload to SIGUSR2, which re-executes the master; verify the unit installed by your distribution before assuming which command performs a stop/start. Plan for a cold-cache latency spike and a brief worker drain.

Account for the interned strings buffer. opcache.interned_strings_buffer (default 8 MB) is allocated inside memory_consumption, not on top of it. Setting 64 MB of memory_consumption with 32 MB of interned strings leaves only 32 MB for actual bytecode.

Setting OPcache directives via php_admin_value[] inside an FPM pool config does not reliably resize the OPcache segment. OPcache shared memory is allocated before pool config is applied, so the directive must come from php.ini or the global FPM config to take effect.

If slots are the binding constraint

Raise opcache.max_accelerated_files. When num_cached_scripts is pinned at the configured prime and there is still free memory, the limit is the slot count, not memory.

opcache.max_accelerated_files=32531

Pick the next prime above your real file count with headroom. find $APP -name '*.php' | wc -l gives the floor; aim for at least 1.5x that. PHP rounds up to the nearest prime from a fixed internal set.

If deploys are the cause

Two deploy patterns reliably fill OPcache without ever triggering a restart:

• New checkout per release. Each release gets its own directory and a symlink flips to it. The same index.php cached under releases/20260720/... and releases/20260721/... consumes two slots, and the old release’s entries never invalidate because nothing loads them anymore.
• Deploy without opcache_reset(). Both old and new bytecode are resident. wasted_memory climbs but the old entries do not free until a restart.

For symlink-per-release or file-overwrite deploys, call opcache_reset() after the symlink flips, or send SIGUSR2 to the FPM master to reload the pool. Both clear the cache and cause a temporary latency spike while workers recompile; do them behind a rolling restart or outside peak traffic. opcache.validate_timestamps=0 in production removes per-request stat() traffic but removes automatic detection of file changes, so you must reset explicitly on every deploy.

Do not reach for these first

• Raising pm.max_children. More workers do not help when every worker is compiling. The constraint is shared memory, not concurrency.
• Adding CPU. Compilation will absorb whatever CPU you add as long as the cache keeps churning.
• Restarting FPM on a schedule. Buys minutes between thrash events. Treat it as a workaround, not a fix.

Prevention

• Monitor hit rate as a first-class signal. Alert on hit rate below 99% sustained after warmup, not on absolute miss counts. Cumulative hit rate masks current thrash behind a long history of hits.
• Track the two capacity ratios. num_cached_scripts / max_accelerated_files and used_memory / memory_consumption should each stay below 0.7.
• Size max_accelerated_files against the real file count. Recompute after adding major dependencies. The default 10000 is too low for most modern framework applications.
• Reset OPcache on every deploy. Treat it as part of the deploy script, not a manual step, regardless of deployment strategy.
• Avoid symlink-per-release without an explicit reset. If you must use them, document the reset step in the deploy tool.
• Separate OPcache monitoring from FPM status polling. The two are independent signal sources and one cannot substitute for the other.

How Netdata helps

• The PHP-FPM collector surfaces pool-level signals (active processes, idle processes, listen queue, max children reached) at one-second resolution, so you can correlate uniform CPU saturation with pool state and rule out worker exhaustion.
• Per-second per-process CPU metrics let you distinguish uniform CPU across all workers (OPcache thrash) from a subset of workers with high CPU and the rest idle (slow dependency drain).
• ML anomaly detection on the metrics Netdata does collect flags thrash onset faster than static thresholds, because cumulative counters hide the rate change.
• Deployment markers (when configured) align a worker-CPU or request-latency rise with the deploy that caused it, removing the guesswork of correlating a slow drift with a release.

If you wire opcache_get_status() into a custom collector, OPcache hit rate and free memory correlate directly with worker CPU and request latency, making the “everything is slow but the FPM status page is fine” pattern immediately legible.

Related guides

• PHP-FPM 504 Gateway Timeout: requests accepted but never finishing in time
• PHP-FPM active processes near max_children: reading pool utilization
• PHP-FPM in containers: cgroup limits and the silent OOM kill
• PHP-FPM “child N exited on signal 11 (SIGSEGV)”: worker segfaults
• PHP-FPM crash loop and fork storm: workers dying faster than they serve
• PHP-FPM dynamic mode scaling lag: why the pool cannot keep up with bursts
• PHP-FPM emergency restart: “failed processes threshold reached, initiating reload”
• PHP-FPM graceful reload: the brief no-worker window on SIGUSR2
• How PHP-FPM actually works in production: a mental model for operators
• PHP-FPM idle processes at zero: no burst headroom left
• PHP-FPM listen queue growing: the earliest signal of saturation
• PHP-FPM “server reached pm.max_children setting (N), consider raising it”