symfony/finder · error · RuntimeException

This iterator only support returning current as fileinfo.

Error message

This iterator only support returning current as fileinfo.

What it means

RecursiveDirectoryIterator (the Finder one) only supports CURRENT_AS_FILEINFO mode; if the $flags bitmask includes SplFilesystemIterator::CURRENT_AS_PATHNAME or CURRENT_AS_SELF it throws RuntimeException because current() would not return the SplFileInfo the Finder ecosystem depends on.

Solutions

  1. Use flags without CURRENT_AS_* overrides, e.g. \FilesystemIterator::SKIP_DOTS | \FilesystemIterator::UNIX_PATHS
  2. If you need pathnames, keep the default (SplFileInfo) and call (string)$file or $file->getPathname()
  3. If you need CURRENT_AS_PATHNAME semantics, use native \RecursiveDirectoryIterator/\RecursiveIteratorIterator instead of this class

Example fix

// before
$it = new RecursiveDirectoryIterator($path, \FilesystemIterator::CURRENT_AS_PATHNAME | \FilesystemIterator::SKIP_DOTS);
// after
$it = new RecursiveDirectoryIterator($path, \FilesystemIterator::SKIP_DOTS);
foreach ($it as $fileInfo) { $path = $fileInfo->getPathname(); }
Defensive patterns

Strategy: validation

Validate before calling

if ($flags & (\FilesystemIterator::CURRENT_AS_PATHNAME | \FilesystemIterator::CURRENT_AS_SELF)) { throw new \RuntimeException('Unsupported CURRENT_AS_* flag'); }

Type guard

function hasSupportedCurrentFlags(int $flags): bool { return ($flags & (\FilesystemIterator::CURRENT_AS_PATHNAME | \FilesystemIterator::CURRENT_AS_SELF)) === 0; }

Try / catch

try { $it = new RecursiveDirectoryIterator($path, $flags); } catch (\RuntimeException $e) { /* fix flags */ }

Prevention

When it happens

Trigger: new RecursiveDirectoryIterator($path, \FilesystemIterator::CURRENT_AS_PATHNAME) or CURRENT_AS_SELF, or building flags with SKIP_DOTS/CURRENT_AS_PATHNAME combos passed into the constructor or Finder internals.

Common situations: Copy-pasting flags from native SplDirectoryIterator usage, trying to iterate pathnames directly instead of via getPathname(), refactoring code that used the SPL iterator's flag semantics.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

AI-assisted analysis of symfony/finder@4d6c057bfd (2026-09-13). Data as JSON: /api/errors/86c97b07cd7663d9. Report an issue: GitHub.

Appendix: source

Thrown at Iterator/RecursiveDirectoryIterator.php:40

 * @extends \RecursiveDirectoryIterator<string, SplFileInfo>
 */
class RecursiveDirectoryIterator extends \RecursiveDirectoryIterator
{
    private bool $ignoreUnreadableDirs;
    private bool $ignoreFirstRewind = true;

    // these 3 properties take part of the performance optimization to avoid redoing the same work in all iterations
    private string $rootPath;
    private string $subPath;
    private string $directorySeparator = '/';

    /**
     * @throws \RuntimeException
     */
    public function __construct(string $path, int $flags, bool $ignoreUnreadableDirs = false)
    {
        if ($flags & (self::CURRENT_AS_PATHNAME | self::CURRENT_AS_SELF)) {
            throw new \RuntimeException('This iterator only support returning current as fileinfo.');
        }

        parent::__construct($path, $flags);
        $this->ignoreUnreadableDirs = $ignoreUnreadableDirs;
        $this->rootPath = $path;
        if ('/' !== \DIRECTORY_SEPARATOR && !($flags & self::UNIX_PATHS)) {
            $this->directorySeparator = \DIRECTORY_SEPARATOR;
        }
    }

    /**
     * Return an instance of SplFileInfo with support for relative paths.
     */
    public function current(): SplFileInfo
    {
        // the logic here avoids redoing the same work in all iterations

        if (!isset($this->subPath)) {

View on GitHub (pinned to 4d6c057bfd)