Fatal Error - Too many open files

Fatal Error - Too many open files

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

Fatal Error - Too many open files

When a PHPUnit test suite suddenly crashes on a new machine with a Fatal error: Too many open files, it is often a symptom of resource exhaustion rather than a code logic error. The stack trace provided in the issue points directly to the culprit:

RecursiveDirectoryIterator::__construct(/usr/lib/php/pear/File/Iterator): failed to open dir: Too many open files

This specific failure occurs within PEAR's file iterator, which PHPUnit relies on to scan directories for test classes. The error message is unambiguous: the operating system has refused to hand over any more file descriptors to the PHP process because it has hit its hard limit. While the PHP version jumped from 5.3.14 to 5.3.21, the underlying constraint isn't the interpreter itself but the kernel's configuration regarding how many files a single process can keep open simultaneously.

Understanding the Limitation

Linux systems impose a default limit on the number of file descriptors per process. This limit is stored in the /proc/[pid]/limits directory or configured via ulimit. In many standard distributions, this value defaults to 1024. While this sounds generous, running a large PHPUnit suite involves opening and scanning thousands of directories and files.

The issue becomes apparent when you run the tests. The output shows:

................EEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEEE 65 / 66 ( 98%)
E

Time: 34 seconds, Memory: 438.50Mb
There were 50 errors:
...
PHP Fatal error: Uncaught exception 'UnexpectedValueException' with message 'RecursiveDirectoryIterator::__construct(/usr/lib/php/pear/File/Iterator): failed to open dir: Too many open files'

The process starts fine, consumes memory (438.50Mb in this case), and eventually hits the wall exactly when trying to iterate through the PEAR library structure to find test classes or scan directories. The PHP version upgrade likely changed how the application spawned or managed resources, but the kernel limit remained static.

Diagnosing the Current State

To confirm this is a file descriptor limit issue, you can check the current setting for the running process. If you are still debugging on the new machine, find the process ID (PID) of your PHP CLI or PHPUnit runner and inspect its limits:

cat /proc/[pid]/limits | grep "open files"

If the soft limit is 1024, that is almost certainly where the crash occurs. The hard limit might be higher, but the soft limit acts as the immediate barrier. You cannot rely on ulimit -n alone if the system administrator has set a global kernel parameter (fs.file-max) too low, though usually, per-process limits are the culprit in development environments.

Resolving the Configuration

The fix involves increasing the file descriptor limit for the PHP process. This can be done temporarily during your session or permanently via system configuration.

To apply it immediately without restarting the machine, run:

ulimit -n 65535
phpunit

If you are running PHPUnit as a service (via nohup or systemd), you must update the limit in the systemd unit file. Edit the .service file associated with your test runner and add:

[Service]
LimitNOFILE=65535

Then reload the daemon and restart the service. For a more permanent solution on the CLI, ensure your shell startup files (like ~/.bashrc) include ulimit -n 65535 before launching any PHP scripts.

Why This Happens Now

It is important to note that simply upgrading PHP from 5.3.14 to 5.3.21 did not inherently cause this crash, nor does the version number dictate file descriptor limits. The kernel limit is independent of the PHP interpreter. However, newer PHP versions or different SAPIs (Server API) might open files differently than older ones, pushing the process closer to the ceiling faster.

If you are using PEAR (as indicated by the /usr/lib/php/pear path in the stack trace), be aware that PEAR installations can be heavy on file handles during installation or scanning phases. Scanning a large directory tree with RecursiveDirectoryIterator is an iterative operation that holds open many file descriptors until the loop completes.

Trade-offs and Considerations

Increasing the limit to 65535 is generally safe for development environments where you are not running high-concurrency network services like Nginx or Apache in the same process context. However, if you are hosting a production PHP application with thousands of concurrent requests, blindly raising this limit might lead to memory exhaustion, as each open file descriptor consumes kernel memory and associated structures.

In such cases, a moderate increase (e.g., to 4096 or 8192) is often sufficient. The goal is to ensure the process has enough headroom to complete its directory scans without hitting the wall, while avoiding resource bloat that could impact system stability under heavy load.

For projects using Laravel, similar issues can arise when running php artisan test or scanning large vendor directories. If you encounter this in a production deployment involving PEAR or legacy libraries, applying the systemd LimitNOFILE directive is the cleanest approach to ensure consistency across environments without relying on developer shell sessions.

Our network