What causes "Quantization limit must be greater than 0" in Intervention/image?

Pass the limit through $image->reduceColors($limit) so the constructor validates it once

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

Quantization limit must be greater than 0

Error message

Quantization limit must be greater than 0

What it means

The Imagick driver's reduceColors() implementation re-checks the quantization limit and throws InvalidArgumentException when it is 0 or negative, because Imagick's quantizeImage() requires a positive color count. Note the generic ReduceColorsModifier constructor already rejects limit < 1 at instantiation with a different message ('Invalid color limit. Must be int<1, max>'), so this driver-level throw is only reachable when the public $limit property is mutated after construction or the specialized modifier is applied by hand. It is a guard against inconsistent state, not normal fluent-API use.

Source

Thrown at src/Drivers/Imagick/Modifiers/ReduceColorsModifier.php:23

namespace Intervention\Image\Drivers\Imagick\Modifiers;

use ImagickException;
use Intervention\Image\Exceptions\InvalidArgumentException;
use Intervention\Image\Exceptions\ModifierException;
use Intervention\Image\Interfaces\ImageInterface;
use Intervention\Image\Interfaces\SpecializedInterface;
use Intervention\Image\Modifiers\ReduceColorsModifier as GenericReduceColorsModifier;

class ReduceColorsModifier extends GenericReduceColorsModifier implements SpecializedInterface
{
    /**
     * @throws InvalidArgumentException
     * @throws ModifierException
     */
    public function apply(ImageInterface $image): ImageInterface
    {
        if ($this->limit <= 0) {
            throw new InvalidArgumentException('Quantization limit must be greater than 0');
        }

        // no color reduction if the limit is higher than the colors in the img
        if ($this->limit > $image->core()->native()->getImageColors()) {
            return $image;
        }

        foreach ($image as $frame) {
            try {
                $result = $frame->native()->quantizeImage(
                    $this->limit,
                    $frame->native()->getImageColorspace(),
                    0,
                    false,
                    false,
                );
                if ($result === false) {
                    throw new ModifierException(

View on GitHub (pinned to 5598b9e397)

Solutions

Pass the limit through $image->reduceColors($limit) so the constructor validates it once
Clamp computed limits to at least 1: max(1, $limit)
Validate the parameter at the request boundary (integer, min:1) with your framework's validator
If you must build modifiers manually, never mutate $limit after construction

Example fix

// before
$modifier->limit = $computedLimit; // 0 from 'dominant color count' analysis
$modifier->apply($image);

// after
$image->reduceColors(max(1, $computedLimit));

Defensive patterns

Strategy: validation

Validate before calling

$limit = (int) $input['colors'];
if ($limit < 1) {
    throw new \InvalidArgumentException('Quantization limit must be >= 1, got ' . $limit);
}
$image->reduceColors($limit);

Type guard

function isValidQuantizationLimit(int $limit): bool
{
    return $limit >= 1;
}

Prevention

Always create the modifier through $image->reduceColors($limit); its constructor enforces int<1, max>
Never overwrite the public $limit property after construction
Validate color-count request parameters with min:1 in your framework's validator

When it happens

Trigger: Creating the modifier with a valid limit, then assigning 0/negative to $modifier->limit before apply(); code that constructs specialized modifiers directly and computes the limit from data that can be 0.

Common situations: Palette-size parameters derived from user input or image analysis (e.g. 'extract N dominant colors' where N can be 0) written straight into the modifier; refactors that bypass the fluent API and lose constructor validation.

Related errors

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