Intervention/image · error · ColorException

Unable to find best color, failed to transform color space f

Error message

Unable to find best color, failed to transform color space for comparision

What it means

While building vibrant/muted theme colors, each palette entry is converted to HSL via toColorspace(Hsl::class) and the result is checked to be an HslColor. This ColorException means at least one palette color failed that conversion, so the category comparison cannot proceed and themeColors() aborts.

Source

Thrown at src/Colors/Themes/VibrantMuted/Definition.php:106

     * Find the best color for a specific category.
     *
     * @throws ColorException
     */
    private function findBestColor(string $category, PaletteInterface $palette): ?ColorInterface
    {
        $bestScore = null;
        $bestColor = null;
        $bestColorHash = null;
        $totalPopulation = $palette->totalCount();

        if ($totalPopulation === 0) {
            return $bestColor;
        }

        foreach ($palette as $color) {
            $hslColor = $color->toColorspace(Hsl::class);
            if (!$hslColor instanceof HslColor) {
                throw new ColorException('Unable to find best color, failed to transform color space for comparision');
            }

            if (!$this->isColorInCategory($hslColor, $category)) {
                continue;
            }

            $population = $palette->colorCount($color);
            $score = $this->calculateScore($hslColor, $population, $totalPopulation, $category);

            if ($this->isBetterColor($color, $score, $bestScore, $bestColorHash)) {
                $bestScore = $score;
                $bestColor = $color;
                $bestColorHash = $this->hashColor($color);
            }
        }

        return $bestColor;
    }

View on GitHub (pinned to 5598b9e397)

Solutions

1. Ensure custom color classes implement toColorspace() such that toColorspace(Hsl::class) returns an HslColor
2. Remove custom color decoders from the chain while using VibrantMuted themes so palettes only contain built-in colors
3. If only built-in classes are involved, report upstream with the image and code

try {
    $themeColors = $image->themeColors();
} catch (ColorException $e) {
    $themeColors = []; // fall back to no theme extraction
}

When it happens

Trigger: Calling themeColors() on an image whose extracted palette contains custom ColorInterface objects whose toColorspace(Hsl::class) does not return an HslColor - typically introduced by custom color decoders registered in the decoder chain.

Common situations: Registering custom color decoder/implementation classes alongside the VibrantMuted theme feature; modifying palette extraction to inject non-standard color objects.

Related errors

• Unable to parse HSL color from input "{input}"
• Number of color channels must be 3 or 4 for {class}
• Normalized color value must be in range 0 to 1
• Unable to import color {colorClass} to {class}
• Failed to import color {colorClass} to {class}

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