{"record":{"id":"056298e7520e91fa","repo":"Intervention/image","slug":"failed-to-import-color-color-class-to-colorspac","errorCode":null,"errorMessage":"Failed to import color {color_class} to {colorspace_class}","messagePattern":"Failed to import color (.+?) to (.+?)","errorType":"exception","errorClass":"Intervention\\Image\\Exceptions\\ColorException","httpStatus":null,"severity":"error","filePath":"src/Colors/Hsv/Colorspace.php","lineNumber":121,"sourceCode":"        );\n\n        // take only RGB\n        $values = array_slice($values, 0, 3);\n\n        // calculate chroma\n        $min = min(...$values);\n        $max = max(...$values);\n        $chroma = $max - $min;\n\n        // calculate value\n        $v = 100 * $max;\n\n        if ($chroma === 0.0) {\n            // grayscale color\n            try {\n                return new Color(0, 0, intval(round($v)), $color->alpha()->normalized());\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        // calculate saturation\n        $s = 100 * ($chroma / $max);\n\n        // calculate hue\n        [$r, $g, $b] = $values;\n        $h = match (true) {\n            ($r === $min) => 3 - (($g - $b) / $chroma),\n            ($b === $min) => 1 - (($r - $g) / $chroma),\n            default => 5 - (($b - $r) / $chroma),\n        } * 60;\n\n        try {","sourceCodeStart":103,"sourceCodeEnd":139,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Colors/Hsv/Colorspace.php#L103-L139","documentation":"Hsv\\Colorspace::importRgbColor() has a special grayscale branch (chroma === 0.0) that constructs Hsv\\Color(0, 0, value, alpha). If that constructor throws an InvalidArgumentException (a channel out of bounds), it is wrapped in this ColorException with the original attached as previous. For valid RgbColor inputs the computed value stays in 0-100, so failures trace back to an out-of-range alpha or corrupted numeric input.","triggerScenarios":"$rgbColor->toColorspace(Hsv\\Colorspace::class) on a grayscale RGB color (r === g === b) where the source color's alpha()->normalized() is outside 0.0-1.0, or NaN channel values produce an invalid intval/round result.","commonSituations":"Custom color implementations returning unnormalized alpha (e.g. 0-100 or 0-255 scale); colors reconstructed from stored raw values without validation; numeric corruption from external pixel pipelines.","solutions":["Inspect $e->getPrevious() for the failing channel and bound","Fix the source alpha to return a normalized 0.0-1.0 float","Rebuild the source RgbColor via its validating constructor before converting","Wrap conversions of untrusted colors in try/catch and use a safe fallback such as Hsv\\Color::create(0, 0, 0)"],"exampleFix":"// before\n$rgb = new RgbColor(128, 128, 128, 128); // alpha accidentally on 0-255 scale\n\n// after\n$rgb = new RgbColor(128, 128, 128, 1.0); // alpha normalized 0.0-1.0","handlingStrategy":"try-catch","validationCode":"$alpha = $rgbColor->alpha()->normalized();\nif (!is_finite($alpha) || $alpha < 0.0 || $alpha > 1.0) {\n    // rebuild with clamped alpha before converting\n    $rgbColor = Rgb\\Color::create(\n        $rgbColor->red()->value(),\n        $rgbColor->green()->value(),\n        $rgbColor->blue()->value(),\n        min(1.0, max(0.0, is_finite($alpha) ? $alpha : 1.0)),\n    );\n}","typeGuard":null,"tryCatchPattern":"use Intervention\\Image\\Exceptions\\ColorException;\n\ntry {\n    $hsv = $rgbColor->toColorspace(Hsv\\Colorspace::class);\n} catch (ColorException $e) {\n    $hsv = Hsv\\Color::create(0, 0, 0); // safe fallback\n}","preventionTips":["Use exactly one alpha scale (0.0-1.0) throughout your codebase","Clamp external opacity values at input, not at conversion time","Inspect getPrevious() to confirm the offending channel"],"tags":["php","intervention-image","color","hsv","rgb","grayscale","colorspace-conversion"],"backgroundTag":"colorspace-conversion-failed","analyzedSha":"5598b9e39751c34afc5cdee84abef77f92c26f68","analyzedAt":"2026-08-23T02:17:31.068Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}