PHP error guide

OPcache serves stale PHP files after deployment: meaning and fix

warning server Affects: PHP 7.4–8.4 Last verified:

Error summary

Use an atomic deployment and a deliberate cache invalidation or affected-pool reload; configure validate_timestamps to match the deployment model.

What it means

Use an atomic deployment and a deliberate cache invalidation or affected-pool reload; configure validate_timestamps to match the deployment model.

What the error means

Workers continue executing cached bytecode after source files changed because timestamp validation is disabled or has not occurred.

Why PHP produces it

Production OPcache is configured for immutable releases, but files were modified in place without invalidating cache or replacing workers.

PHP version notes

The behavior described for OPcache serves stale PHP files after deployment applies to PHP 7.4–8.4 unless a narrower version is stated; exact wording can vary by SAPI and patch release.

Most common causes

  • opcache.validate_timestamps=0 and files are overwritten in place.
  • A deployment calls opcache_reset through CLI, which resets only the CLI cache.
  • Multiple FPM pools or nodes are not all reloaded.

Minimal examples

BAD — reproduces the problem

shell 
php -r "opcache_reset();"
# assumes this clears FPM OPcache

FIXED — safer pattern

shell 
# atomically activate a new release, then reload only the affected PHP-FPM pool

Step-by-step diagnosis

  1. Inspect opcache_get_configuration and status from the affected web SAPI.
  2. Compare release path, file mtime, and cached script metadata.
  3. Verify every serving pool/node received the deployment action.

Fixes

Match invalidation to deployment

For immutable releases, switch the symlink then reload the affected pool; for mutable development, enable timestamp checks.

ini 
; development
opcache.validate_timestamps=1
opcache.revalidate_freq=0

; immutable production: deploy a new release path, then reload its FPM pool

Common mistakes when fixing it

  • Calling an unauthenticated web opcache_reset endpoint.
  • Restarting unrelated PHP services.
  • Disabling OPcache permanently.

How to prevent it

  • Use immutable versioned release directories.
  • Automate scoped pool reloads or authenticated invalidation.
  • Verify release identity from each node.

Web server / environment notes

fpm, apache, cli, linux. Each SAPI and process cache must be invalidated in its own execution context.

Tags: fpm,apache,cli,linux

Categories