filesize(): stat failed for specific path - php

filesize(): stat failed for specific path - php

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

Stefan Bogdanescu

Founder & Senior Architect

filesize(): stat failed for specific path - php

When debugging PHP scripts that scan directories, encountering a "filesize(): stat failed" error is often more about how the operating system resolves paths than it is about a flaw in the language itself. In the scenario where file size and type detection fail specifically within a subdirectory like ./documents but work perfectly in the current working directory (.), the root cause is almost invariably path resolution.

The code snippet provided iterates through a directory using the dir() function:

$path = "./documents";
$dh = dir($path);
while( ($file=$dh->read()) ) {
    if( $file=="." || $file=="..")continue;
    // ... logic ...
    echo filesize($file); 
}

The issue stems from how $file is constructed. The dir() function returns filenames relative to the directory handle passed to it. When you pass "./documents" to dir(), the returned $file strings are just names like "report.pdf". However, when you pass that bare filename directly to filesize($file), PHP attempts to resolve it relative to the current working directory (CWD), not the parent of the files listed.

If your script is running from /var/www/html and the files are actually located in /var/www/html/documents, calling filesize("report.pdf") looks for a file named report.pdf inside /var/www/html. If that file doesn't exist there (which it likely doesn't, since it's inside the documents folder), PHP throws a "stat failed" error because the path is invalid relative to the CWD.

To fix this, you must construct an absolute or fully qualified relative path before calling filesystem functions. The most robust approach is to combine the base path with the file name:

$path = "./documents";
$dh = dir($path);
while( ($file=$dh->read()) ) {
    if( $file=="." || $file=="..")continue;
    
    // Construct the full path for filesystem functions
    $fullPath = $path . "/" . $file;
    
    echo filesize($fullPath);
}

By explicitly concatenating $path and $file, you ensure that filesize() receives a valid path like "./documents/report.pdf". This resolves the ambiguity regarding where the file actually resides.

This same logic applies to the icon display issue mentioned in the source material. The original code checks is_file($file) using just the filename. If $file is "report.pdf", is_file("report.pdf") returns false because that specific name doesn't exist in the CWD root; it exists inside the subdirectory. Consequently, the script incorrectly identifies every item as a folder and serves the folder icon. Using the constructed $fullPath for the is_file() check ensures the function looks in the correct location:

$isFile = is_file($fullPath);
echo ($isFile) ? "<img src='file.jpg'/> FILE" : "<img src='folder.jpg'/> FOLDER";

There are nuances to consider when handling paths in PHP. Relative paths are fragile and depend entirely on the server's configuration, specifically open_basedir restrictions and the script's execution context (CWD). If you are deploying this to a production environment, relying solely on relative paths like "./documents" can break if the web root changes or if the script is called via CLI with different parameters.

For higher reliability, especially in larger applications, it is often better to determine the absolute path of the document root. You can use dirname(__DIR__) combined with a constant defining your documents location. This decouples the file logic from the current working directory, making the script resilient to changes in how the application is invoked.

If you are building a larger content management system or need advanced file handling features beyond basic PHP functions, frameworks like Laravel offer utilities that abstract these path resolution headaches. For instance, using public_path('documents') combined with the framework's filesystem facade ensures consistent behavior across different environments without needing to manually calculate relative offsets.

Ultimately, the error message "stat failed" is a direct indicator that the path you are passing to the function does not point to an existing resource on the disk. By explicitly constructing the full path before invoking filesize() or is_file(), you align your code with how the operating system expects paths to be interpreted.

Our network