{"record":{"id":"686547cbbf23d223","repo":"Intervention/image","slug":"the-region-must-fit-within-the-actual-image-size","errorCode":null,"errorMessage":"The region must fit within the actual image size","messagePattern":"The region must fit within the actual image size","errorType":"exception","errorClass":"Intervention\\Image\\Exceptions\\InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"src/Analyzers/AbstractPaletteAnalyzer.php","lineNumber":59,"sourceCode":"     * @return Generator<array<int, int>>\n     */\n    protected function sampleCoordinates(SizeInterface $size, ?SizeInterface $region = null): Generator\n    {\n        $region = $region === null ? $size : $region;\n\n        $startX = $region->pivot()->x();\n        $startY = $region->pivot()->y();\n        $width = $region->width();\n        $height = $region->height();\n\n        // validate the region including its position, otherwise offset\n        // regions would sample coordinates outside of the image\n        if (\n            $startX < 0 || $startY < 0\n            || $startX + $width > $size->width()\n            || $startY + $height > $size->height()\n        ) {\n            throw new InvalidArgumentException('The region must fit within the actual image size');\n        }\n\n        $totalPixels = $width * $height;\n\n        $sampleRate = match (true) {\n            $totalPixels <= 10000 => 1, // <= 10k pixels: sample all\n            $totalPixels <= 100000 => 5, // 10k-100k: every 5th pixel\n            $totalPixels <= 500000 => 10, // 100k-500k: every 10th pixel\n            $totalPixels <= 2000000 => 20, // 500k-2m: every 20th pixel\n            default => 30, // > 2m: every 30th pixel\n        };\n\n        $endX = $startX + $width;\n        $endY = $startY + $height;\n\n        for ($y = $startY; $y < $endY; $y += $sampleRate) {\n            for ($x = $startX; $x < $endX; $x += $sampleRate) {\n                yield [$x, $y];","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Analyzers/AbstractPaletteAnalyzer.php#L41-L77","documentation":"This FileNotFoundException means the path inside your SplFileInfo exists but is not a regular file: is_file() returned false, so the path most likely points at a directory (or a special filesystem entry like a FIFO/socket). The directory check (is_dir on the dirname) and file_exists() both passed before reaching this guard in filePathFromSplFileInfoOrFail(), so the entry is present on disk but is the wrong type.","triggerScenarios":"ImageManager::read(new SplFileInfo($dir)) where $dir is a directory like storage_path('app') (its dirname exists and the entry itself exists, but it is a directory); passing a path that ends without a filename (e.g. trailing slash stripped to the folder); a symlink inside the path resolving to a directory; passing an SplFileInfo for a Unix special file.","commonSituations":"Building paths dynamically where the filename segment is empty and the path collapses to a folder; user-submitted 'path' fields that are actually folder names; scripts iterating DirectoryIterator and accidentally feeding the current directory entry ('.') or a subdirectory to read(); symlinks in upload dirs pointing at folders.","solutions":["Check $splFileInfo->isFile() before calling read() and reject directories early","Inspect getPathname() output: if it ends up being a folder, append the intended filename segment","When iterating directories, skip entries where isDir() is true before processing"],"exampleFix":"// before\nforeach (new DirectoryIterator($dir) as $file) {\n    $images[] = $manager->read($file); // throws on subdirectories\n}\n\n// after\nforeach (new DirectoryIterator($dir) as $file) {\n    if ($file->isFile()) {\n        $images[] = $manager->read($file);\n    }\n}","handlingStrategy":"validation","validationCode":"if (!$splFileInfo->isFile()) {\n    throw new \\InvalidArgumentException(\n        'Expected a regular file, got: ' . $splFileInfo->getPathname()\n    );\n}\n$image = $manager->read($splFileInfo);","typeGuard":"function isRegularImageFile(\\SplFileInfo $info, array $exts = ['jpg','jpeg','png','gif','webp']): bool\n{\n    return $info->isFile()\n        && in_array(strtolower($info->getExtension()), $exts, true);\n}","tryCatchPattern":"use Intervention\\Image\\Exceptions\\FileNotFoundException;\n\ntry {\n    $image = $manager->read($file);\n} catch (FileNotFoundException $e) {\n    // message contains 'is no file in directory' when the entry exists but is a folder\n    if (str_contains($e->getMessage(), 'is no file')) {\n        // path points at a directory: fix the path builder\n    }\n}","preventionTips":["Always build paths as dirname + DIRECTORY_SEPARATOR + explicit filename; never pass a bare folder","When iterating directories, filter with isFile() before feeding entries to the manager","Reject trailing-slash paths from user input"],"tags":["not-a-regular-file","splfileinfo","directory-entry","intervention-image"],"backgroundTag":"path-is-not-a-file","analyzedSha":"5598b9e39751c34afc5cdee84abef77f92c26f68","analyzedAt":"2026-08-23T02:17:31.068Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}