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

Unable to sort by color channel {channel}

Error message

Unable to sort by color channel {channel}

What it means

The value passed to sortByChannel() is an existing class, but not one of the channel classes Intervention Image knows how to sort by. A match expression maps only the built-in RGB, CMYK, HSL, HSV, OkLab and OkLCH channel classes to their sort colorspace; anything else (a custom channel class, a color class, a colorspace class) falls through to the default arm and throws.

Source

Thrown at src/Colors/Palette.php:339

            Cmyk\Channels\Key::class,
            Cmyk\Channels\Alpha::class => Cmyk\Colorspace::class,
            Hsl\Channels\Hue::class,
            Hsl\Channels\Saturation::class,
            Hsl\Channels\Luminance::class,
            Hsl\Channels\Alpha::class => Hsl\Colorspace::class,
            Hsv\Channels\Hue::class,
            Hsv\Channels\Saturation::class,
            Hsv\Channels\Value::class,
            Hsv\Channels\Alpha::class => Hsv\Colorspace::class,
            Oklab\Channels\Lightness::class,
            Oklab\Channels\A::class,
            Oklab\Channels\B::class,
            Oklab\Channels\Alpha::class => Oklab\Colorspace::class,
            Oklch\Channels\Lightness::class,
            Oklch\Channels\Chroma::class,
            Oklch\Channels\Hue::class,
            Oklch\Channels\Alpha::class => Oklch\Colorspace::class,
            default => throw new InvalidArgumentException('Unable to sort by color channel ' . $channel),
        };

        // create indexed array to track original colors
        $originalBins = $this->bins;
        $indices = array_keys($originalBins);

        // sort indices based on channel values in the sort colorspace; each
        // color is converted individually because palettes may mix colorspaces
        usort(
            $indices,
            function (
                string $indexA,
                string $indexB,
            ) use (
                $channel,
                $sortColorspace,
                $originalBins,
            ): int {

View on GitHub (pinned to 5598b9e397)

Solutions

1. Pass one of the built-in channel classes, e.g. Rgb\Channels\Red::class, Hsv\Channels\Value::class, Oklch\Channels\Hue::class
2. Sort by a channel object from an existing color: $palette->sortByChannel($color->channel(Red::class))
3. For custom channels, convert the palette first with $palette->toColorspace(...) and sort by a supported native channel of that colorspace
4. For arbitrary sort criteria, use $palette->toArray() with usort() instead

Example fix

// before
$palette->sortByChannel(\App\Colors\CustomChannel::class);

// after
$palette->sortByChannel(\Intervention\Image\Colors\Rgb\Channels\Red::class);

use Intervention\Image\Colors\Rgb\Channels\Red;
use Intervention\Image\Colors\Rgb\Channels\Green;
use Intervention\Image\Colors\Rgb\Channels\Blue;

$supported = [Red::class, Green::class, Blue::class /* + other colorspace channels */];
if (!in_array($channel, $supported, true)) {
    throw new \InvalidArgumentException('Channel not sortable: ' . $channel);
}
$palette->sortByChannel($channel);

function isSortableChannel(string $channel): bool
{
    return in_array($channel, [
        \Intervention\Image\Colors\Rgb\Channels\Red::class,
        \Intervention\Image\Colors\Rgb\Channels\Green::class,
        \Intervention\Image\Colors\Rgb\Channels\Blue::class,
        \Intervention\Image\Colors\Rgb\Channels\Alpha::class,
        // CMYK, HSL, HSV, OkLab, OkLCH channel classes ...
    ], true);
}

try {
    $palette->sortByChannel($channel);
} catch (\Intervention\Image\Exceptions\InvalidArgumentException $e) {
    // channel unsupported for sorting; fall back to presence order
    $palette->sortByPresence();
}

When it happens

Trigger: sortByChannel(\Intervention\Image\Colors\Rgb\Color::class) (a color class, not a channel class), a user-defined class implementing ColorChannelInterface, or any FQCN outside the supported channel list matched in Palette::sortByChannel().

Common situations: Extending the library with a custom colorspace/channel and assuming sortByChannel() picks it up; passing Rgb\Colorspace::class instead of a channel class; expecting a channel from one colorspace to sort a palette stored in another without conversion.

Related errors

• The channel class "{channel}" does not exist
• Unable to set color via array access, use addColor() instead
• Unable to remove color from palette via array access
• Quantization levels value must be between 1 and 256
• Failed to apply {class}, unable to process quantization

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