Warning: Zend OPcache huge_code_pages: madvise(HUGEPAGE) failed: Cannot allocate memory / OPcache restart scheduled
ID: php/opcache-restart
Version Compatibility
| Version | Status | Introduced | Deprecated | Notes |
|---|---|---|---|---|
| 83 | active | — | — | — |
Root Cause
OPcache restart errors occur when the OPcache shared memory segment runs out of space, forcing a cache invalidation and restart. This causes a temporary performance degradation as all scripts must be recompiled. Common with large codebases, frequent deployments, or undersized opcache.memory_consumption settings.
genericWorkarounds
-
90% success Increase OPcache memory allocation and key limits based on actual usage
Check current usage with opcache_get_status(). Increase settings in php.ini: 'opcache.memory_consumption=256' (MB), 'opcache.interned_strings_buffer=32' (MB), 'opcache.max_accelerated_files=20000'. The max_accelerated_files should be larger than the total number of PHP files in the project. Restart PHP-FPM after changes.
-
86% success Use opcache_reset() or php-fpm reload on deployment instead of relying on file monitoring
Set 'opcache.validate_timestamps=0' in production to never check for file changes. On each deployment, reload PHP-FPM with 'systemctl reload php8.3-fpm' which gracefully restarts workers and clears the cache. Alternatively, call opcache_reset() from a deployment script via a restricted endpoint.
Dead Ends
Common approaches that don't work:
-
Disabling OPcache entirely to avoid the restart warnings
88% fail
Disabling OPcache removes the performance benefits of opcode caching, causing every PHP file to be parsed and compiled on every request. This can increase response times by 2-10x and significantly increase CPU usage on the server.
-
Setting opcache.revalidate_freq to 0 in production
70% fail
Setting revalidate_freq to 0 causes OPcache to check every file for changes on every request, which defeats the caching purpose and adds filesystem stat calls to every request. In production, files should not change between deployments.