{"record":{"id":"565478686c7ac7d1","repo":"Intervention/image","slug":"unable-to-find-best-color-failed-to-transform-col","errorCode":null,"errorMessage":"Unable to find best color, failed to transform color space for comparision","messagePattern":"Unable to find best color, failed to transform color space for comparision","errorType":"exception","errorClass":"ColorException","httpStatus":null,"severity":"error","filePath":"src/Colors/Themes/VibrantMuted/Definition.php","lineNumber":106,"sourceCode":"     * Find the best color for a specific category.\n     *\n     * @throws ColorException\n     */\n    private function findBestColor(string $category, PaletteInterface $palette): ?ColorInterface\n    {\n        $bestScore = null;\n        $bestColor = null;\n        $bestColorHash = null;\n        $totalPopulation = $palette->totalCount();\n\n        if ($totalPopulation === 0) {\n            return $bestColor;\n        }\n\n        foreach ($palette as $color) {\n            $hslColor = $color->toColorspace(Hsl::class);\n            if (!$hslColor instanceof HslColor) {\n                throw new ColorException('Unable to find best color, failed to transform color space for comparision');\n            }\n\n            if (!$this->isColorInCategory($hslColor, $category)) {\n                continue;\n            }\n\n            $population = $palette->colorCount($color);\n            $score = $this->calculateScore($hslColor, $population, $totalPopulation, $category);\n\n            if ($this->isBetterColor($color, $score, $bestScore, $bestColorHash)) {\n                $bestScore = $score;\n                $bestColor = $color;\n                $bestColorHash = $this->hashColor($color);\n            }\n        }\n\n        return $bestColor;\n    }","sourceCodeStart":88,"sourceCodeEnd":124,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Colors/Themes/VibrantMuted/Definition.php#L88-L124","documentation":"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.","triggerScenarios":"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.","commonSituations":"Registering custom color decoder/implementation classes alongside the VibrantMuted theme feature; modifying palette extraction to inject non-standard color objects.","solutions":["Ensure custom color classes implement toColorspace() such that toColorspace(Hsl::class) returns an HslColor","Remove custom color decoders from the chain while using VibrantMuted themes so palettes only contain built-in colors","If only built-in classes are involved, report upstream with the image and code"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    $themeColors = $image->themeColors();\n} catch (ColorException $e) {\n    $themeColors = []; // fall back to no theme extraction\n}","preventionTips":["Do not mix custom color implementations into palettes used by theme extraction","Test custom color classes with toColorspace(Hsl::class) before registering them"],"tags":["color","colorspace","hsl","theme","palette"],"backgroundTag":"colorspace-conversion-failed","analyzedSha":"5598b9e39751c34afc5cdee84abef77f92c26f68","analyzedAt":"2026-08-23T02:17:31.068Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}