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

resolveDriver() (used by ImageManager::__construct to build the driver from your 'driver' option) throws this InvalidArgumentException when the driver is given as a string that is not an existing class name. Intervention Image v3 expects fully-qualified driver class names such as \Intervention\Image\Drivers\Gd\Driver::class, not short identifiers like 'gd' or 'imagick'.

Source

Thrown at src/Analyzers/PopularPaletteAnalyzer.php:28

use Intervention\Image\Interfaces\ColorInterface;
use Intervention\Image\Interfaces\ImageInterface;
use Intervention\Image\Interfaces\PaletteInterface;
use Intervention\Image\Interfaces\SizeInterface;
use Intervention\Image\Traits\CanHashColor;

class PopularPaletteAnalyzer extends AbstractPaletteAnalyzer
{
    use CanHashColor;

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

    /**
     * {@inheritdoc}
     *
     * @see AnalyzerInterface::analyze()
     *
     * @throws InvalidArgumentException
     * @throws AnalyzerException
     */
    public function analyze(ImageInterface $image): PaletteInterface
    {
        $colors = iterator_to_array($this->collectColors($image, $this->region));
        $popular = new Palette($colors);

        return $popular
            ->reduce($this->quantizationLevels($colors))

View on GitHub (pinned to 5598b9e397)

Solutions

1. Pass the class constant: new ImageManager(['driver' => \Intervention\Image\Drivers\Gd\Driver::class]) (or the Imagick equivalent)
2. Add the correct use Intervention\Image\Drivers\Gd\Driver; import at the top of the file and use Driver::class
3. For custom drivers, run composer dump-autoload and verify the class exists with class_exists() in a tinker/script
4. After fixing, clear cached config (php artisan config:clear) if the value comes from a config file

Example fix

// before (v2 style, throws in v3)
$manager = new ImageManager(['driver' => 'gd']);

// after (v3)
use Intervention\Image\Drivers\Gd\Driver;
$manager = new ImageManager(['driver' => Driver::class]);

$driver = $config['driver'] ?? null;
if (is_string($driver) && !class_exists($driver)) {
    throw new \RuntimeException('Unknown driver class: ' . $driver);
}
$manager = new \Intervention\Image\ImageManager(['driver' => $driver]);

use Intervention\Image\Interfaces\DriverInterface;

/** Normalizes user config into a valid driver class name or fails early. */
function resolveDriverClass(string|DriverInterface $driver): string|DriverInterface
{
    if (is_object($driver)) {
        return $driver;
    }
    if (!class_exists($driver)) {
        throw new \InvalidArgumentException('Driver class does not exist: ' . $driver);
    }
    return $driver;
}

use Intervention\Image\Exceptions\InvalidArgumentException;

try {
    $manager = new \Intervention\Image\ImageManager(['driver' => $driverName]);
} catch (InvalidArgumentException $e) {
    // 'must be existing class name': fall back to a shipped driver
    $manager = new \Intervention\Image\ImageManager(
        ['driver' => \Intervention\Image\Drivers\Gd\Driver::class]
    );
}

When it happens

Trigger: new ImageManager(['driver' => 'gd']) or 'imagick' (strings are not class names in v3); typos like 'Intervention\Image\Drivers\Gd\Drive'; using ::class on a missing import (GdDriver::class without the use statement resolves to the wrong namespace); referencing a custom driver class that is not autoloadable (wrong PSR-4 path, composer dump-autoload needed).

Common situations: Upgrading from Intervention Image v2 (which accepted 'gd'/'imagick' strings) to v3 without updating the config; Laravel config files caching an old driver value after upgrade; custom driver classes moved or renamed; autoload cache stale after composer changes.

Related errors

• Call to undefined method Intervention\Image\Image::{name}()
• Color channel {classname} could not be found
• Unknown color space ({colorspace}) as conversion target
• Argument $extension must not be an empty string
• Unable to extract file extension from path "' . $this->path

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