{"record":{"id":"8916d2e1b27eae0f","repo":"Intervention/image","slug":"failed-to-import-named-color-to-rgb-color-space","errorCode":null,"errorMessage":"Failed to import named color to rgb color space","messagePattern":"Failed to import named color to rgb color space","errorType":"exception","errorClass":"ColorException","httpStatus":null,"severity":"error","filePath":"src/Colors/Rgb/Colorspace.php","lineNumber":279,"sourceCode":"            );\n        }\n\n        return $this->importOklabColor($color);\n    }\n\n    /**\n     * Import given named color to RGB color space.\n     *\n     * @throws ColorException\n     */\n    private function importNamedColor(NamedColor $color): RgbColor\n    {\n        try {\n            $output = InputHandler::usingDecoders([\n                HexColorDecoder::class,\n            ])->handle($color->toHex());\n        } catch (InvalidArgumentException | NotSupportedException | DriverException $e) {\n            throw new ColorException('Failed to import named color to rgb color space', previous: $e);\n        }\n\n        return $output instanceof RgbColor\n            ? $output\n            : throw new ColorException('Failed to import named color to rgb color space');\n    }\n}\n","sourceCodeStart":261,"sourceCodeEnd":287,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Colors/Rgb/Colorspace.php#L261-L287","documentation":"Named colors are imported to RGB by writing the color's hex string (NamedColor::toHex()) and re-reading it through HexColorDecoder. This ColorException wraps any InvalidArgumentException, NotSupportedException or DriverException raised during that re-parse, with the original chained. With built-in NamedColor objects the hex string is always valid, so failures come from custom NamedColor subclasses whose toHex() returns a malformed value.","triggerScenarios":"A NamedColor subclass overriding toHex() to return a non-hex or wrongly-shaped string (e.g. 'rgb(255,0,0)' or 'ff0z'), then converted via toColorspace(Rgb\\Colorspace::class) or importColor().","commonSituations":"Custom named-color classes added to support brand palettes or themes; overriding toHex() for formatting concerns (prefixes, shorthand) and breaking the decoder round-trip; themes built on a modified color registry.","solutions":["Make custom toHex() return a valid hex string of 3, 4, 6 or 8 hex digits (with or without leading '#')","Read $e->getPrevious() to see the underlying hex decode failure","Prefer overriding the value passed to the parent NamedColor constructor instead of toHex()"],"exampleFix":"// before\nclass BrandRed extends \\Intervention\\Image\\Colors\\Rgb\\NamedColor {\n    public static function toHex(): string { return 'rgb(255,0,0)'; } // breaks hex round-trip\n}\n\n// after\nclass BrandRed extends \\Intervention\\Image\\Colors\\Rgb\\NamedColor {\n    public static function toHex(): string { return 'ff0000'; }\n}","handlingStrategy":"try-catch","validationCode":"$hex = $namedColor::toHex();\nif (!preg_match('/^#?([a-f\\d]{3}|[a-f\\d]{4}|[a-f\\d]{6}|[a-f\\d]{8})$/i', $hex)) {\n    throw new \\RuntimeException('NamedColor::toHex() must return valid hex, got: ' . $hex);\n}\n$rgb = $namedColor->toColorspace(\\Intervention\\Image\\Colors\\Rgb\\Colorspace::class);","typeGuard":null,"tryCatchPattern":"try {\n    $rgb = $namedColor->toColorspace(\\Intervention\\Image\\Colors\\Rgb\\Colorspace::class);\n} catch (\\Intervention\\Image\\Exceptions\\ColorException $e) {\n    $previous = $e->getPrevious(); // hex decode failure details\n    $rgb = \\Intervention\\Image\\Colors\\Rgb\\Color::fromHex('ff0000'); // safe fallback\n}","preventionTips":["Custom NamedColor subclasses must keep toHex() a valid 3/4/6/8-digit hex string","Do not format toHex() output (prefixes, spacing, shorthand variants)","Unit-test custom named colors by round-tripping them through toColorspace(Rgb)"],"tags":["colorspace-conversion","named-colors","hex","php"],"backgroundTag":"colorspace-conversion-failed","analyzedSha":"5598b9e39751c34afc5cdee84abef77f92c26f68","analyzedAt":"2026-08-23T02:17:31.068Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}