What causes "Invalid $limit value. Must be int " in Intervention/image?

Grant directory read+execute access for the PHP user: chmod 755 (or chown to the PHP-FPM user)

Intervention/image · error · Intervention\Image\Exceptions\InvalidArgumentException

Invalid $limit value. Must be int<1, max>

Error message

Invalid $limit value. Must be int<1, max>

What it means

This FileNotReadableException is thrown when the directory stored in your SplFileInfo exists and the target file exists, but the PHP process lacks read permission on the directory itself (is_readable($dirname) is false). filePathFromSplFileInfoOrFail() checks directory readability before file readability, so this specifically points at the containing folder, not the file.

Source

Thrown at src/Analyzers/DominantPaletteAnalyzer.php:55

    /**
     * Fixed seed for deterministic results.
     */
    private const SEED = 1024;

    /**
     * Local RNG.
     */
    private Randomizer $rng;

    /**
     * Create new instance.
     *
     * @throws InvalidArgumentException
     */
    public function __construct(protected int $limit = 8, protected ?SizeInterface $region = null)
    {
        if ($this->limit < 1) {
            throw new InvalidArgumentException('Invalid $limit value. Must be int<1, max>');
        }

        $this->randomize();
    }

    /**
     * Analyze dominant colors in given image.
     *
     * @throws InvalidArgumentException
     * @throws AnalyzerException
     */
    public function analyze(ImageInterface $image): PaletteInterface
    {
        // re-seed on every run so the result only depends on the image
        $this->randomize();

        $points = $this->clusterableColors($this->collectColors($image, $this->region));
        $clusters = $this->kMeansClustering($points); // perform K-means clustering

View on GitHub (pinned to 5598b9e397)

Solutions

Grant directory read+execute access for the PHP user: chmod 755 <dirname> (or chown to the PHP-FPM user)
Confirm which user PHP runs as (posix_getuid()/posix_getpwuid()) and check ownership with ls -ld on the directory
If the permissions are intentional, move/copy the image into a directory the process can read before calling read()

Example fix

# before: directory not readable by www-data
ls -ld /var/app/uploads   # drwx------ root root

# after
chown -R www-data:www-data /var/app/uploads   # or: chmod 755 /var/app/uploads

Defensive patterns

Strategy: validation

Validate before calling

$path = $splFileInfo->getPathname();
$dirname = dirname($path);
if (!is_dir($dirname) || !is_readable($dirname)) {
    throw new \RuntimeException('Storage directory missing or unreadable: ' . $dirname);
}
$image = $manager->read($splFileInfo);

Try / catch

use Intervention\Image\Exceptions\FileNotReadableException;

try {
    $image = $manager->read($file);
} catch (FileNotReadableException $e) {
    // message says 'Directory ... is not readable': fix dir perms (chmod 755) or ownership
}

Prevention

Standardize storage directories to 0755 and files to 0644 at creation time
Run CLI workers and web PHP under the same user/group, or use a shared group with group-read
Add a deployment check that verifies is_readable() on storage paths as the PHP user

When it happens

Trigger: ImageManager::read(new SplFileInfo('/root/photo.png')) on a /root with mode 700 while PHP runs as www-data; uploads stored in a 0700 directory owned by a deploy user while the web server user must read it; containers where the process UID differs from the volume owner; directory mode 0111 (execute-only, no read on the dir itself).

Common situations: CLI scripts run as root creating files/dirs that the web server user later cannot traverse or list; Docker volumes with wrong ownership; hardened production filesystems where dirs are 0700 by default; switching from mod_php to php-fpm changes the effective user.

Related errors

AI-assisted analysis of Intervention/image@5598b9e397 (2026-08-23). Data as JSON: /api/errors/781a0189303ac4f6. Report an issue: GitHub.