{"record":{"id":"ff923c37e10adaf5","repo":"Intervention/image","slug":"failed-to-import-color-colorclass-to-class-ff923c","errorCode":null,"errorMessage":"Failed to import color {colorClass} to {class}","messagePattern":"Failed to import color (.+?) to (.+?)","errorType":"exception","errorClass":"Intervention\\Image\\Exceptions\\ColorException","httpStatus":null,"severity":"error","filePath":"src/Colors/Hsl/Colorspace.php","lineNumber":136,"sourceCode":"        $hue = match (true) {\n            ($delta === 0.0) => 0,\n            ($max === $r) => 60 * fmod((($g - $b) / $delta), 6),\n            ($max === $g) => 60 * ((($b - $r) / $delta) + 2),\n            ($max === $b) => 60 * ((($r - $g) / $delta) + 4),\n            default => 0,\n        };\n\n        $hue = (round($hue) + 360) % 360; // normalize hue\n\n        try {\n            return new Color(\n                intval(round($hue)),\n                intval(round($saturation * 100)),\n                intval(round($luminance * 100)),\n                $color->alpha()->normalized(),\n            );\n        } catch (InvalidArgumentException $e) {\n            throw new ColorException(\n                'Failed to import color ' . $color::class . ' to ' . $this::class,\n                previous: $e,\n            );\n        }\n    }\n\n    /**\n     * Import given HSV color to HSL colorspace.\n     *\n     * @throws ColorException\n     */\n    private function importHsvColor(HsvColor $color): HslColor\n    {\n        // normalized values of hsv channels\n        [$h, $s, $v] = array_map(\n            fn(ColorChannelInterface $channel): float => $channel->normalized(),\n            $color->channels(),\n        );","sourceCodeStart":118,"sourceCodeEnd":154,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Colors/Hsl/Colorspace.php#L118-L154","documentation":"When Hsl\\Colorspace::importRgbColor() converts an RgbColor to HSL, it computes hue (0-360), saturation and luminance (0-100) and constructs an Hsl\\Color with the source alpha. If that constructor rejects a value (InvalidArgumentException from a channel), it is re-thrown as this ColorException with the constructor error attached as previous. With valid RgbColor input the math stays in range, so in practice the alpha channel of the source is the usual culprit.","triggerScenarios":"$rgbColor->toColorspace(Hsl\\Colorspace::class) where the source color's alpha()->normalized() is outside 0.0-1.0 (custom color implementations, colors reconstructed from unvalidated storage), or NaN/infinite channel values producing invalid computed hue/saturation/luminance.","commonSituations":"Custom ColorInterface implementations or wrappers that return unnormalized alpha; colors unserialized from cache without re-validation; numerically corrupted channel data from external image analysis pipelines.","solutions":["Check $e->getPrevious() for the exact channel and bound that failed","Ensure the source color's alpha()->normalized() returns a value clamped to [0,1]","Rebuild the source color from validated integers/floats before converting","If conversion of arbitrary colors must never fail, catch ColorException and fall back to a default Hsl\\Color"],"exampleFix":"// before\n$alpha = $row['opacity']; // e.g. 50 (percent scale)\n$rgb = new RgbColor(255, 0, 0, $alpha);\n\n// after\n$alpha = $row['opacity'] / 100; // normalized scale\n$rgb = new RgbColor(255, 0, 0, $alpha);","handlingStrategy":"try-catch","validationCode":"$alpha = $rgbColor->alpha()->normalized();\nif ($alpha < 0.0 || $alpha > 1.0) {\n    $rgbColor = Rgb\\Color::create(\n        $rgbColor->red()->value(),\n        $rgbColor->green()->value(),\n        $rgbColor->blue()->value(),\n        min(1.0, max(0.0, $alpha)),\n    );\n}","typeGuard":null,"tryCatchPattern":"use Intervention\\Image\\Exceptions\\ColorException;\n\ntry {\n    $hsl = $rgbColor->toColorspace(Hsl\\Colorspace::class);\n} catch (ColorException $e) {\n    $hsl = Hsl\\Color::create(0, 0, 0); // safe default\n}","preventionTips":["Keep alpha normalized (0.0-1.0) on every color you create","Check getPrevious() to find the failing channel quickly","Rebuild colors from validated scalars after deserialization"],"tags":["php","intervention-image","color","hsl","rgb","colorspace-conversion"],"backgroundTag":"colorspace-conversion-failed","analyzedSha":"5598b9e39751c34afc5cdee84abef77f92c26f68","analyzedAt":"2026-08-23T02:17:31.068Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}