Intervention/image · error · ColorException

Failed to import named color to rgb color space

Error message

Failed to import named color to rgb color space

What it means

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.

Source

Thrown at src/Colors/Rgb/Colorspace.php:279

            );
        }

        return $this->importOklabColor($color);
    }

    /**
     * Import given named color to RGB color space.
     *
     * @throws ColorException
     */
    private function importNamedColor(NamedColor $color): RgbColor
    {
        try {
            $output = InputHandler::usingDecoders([
                HexColorDecoder::class,
            ])->handle($color->toHex());
        } catch (InvalidArgumentException | NotSupportedException | DriverException $e) {
            throw new ColorException('Failed to import named color to rgb color space', previous: $e);
        }

        return $output instanceof RgbColor
            ? $output
            : throw new ColorException('Failed to import named color to rgb color space');
    }
}

View on GitHub (pinned to 5598b9e397)

Solutions

1. Make custom toHex() return a valid hex string of 3, 4, 6 or 8 hex digits (with or without leading '#')
2. Read $e->getPrevious() to see the underlying hex decode failure
3. Prefer overriding the value passed to the parent NamedColor constructor instead of toHex()

Example fix

// before
class BrandRed extends \Intervention\Image\Colors\Rgb\NamedColor {
    public static function toHex(): string { return 'rgb(255,0,0)'; } // breaks hex round-trip
}

// after
class BrandRed extends \Intervention\Image\Colors\Rgb\NamedColor {
    public static function toHex(): string { return 'ff0000'; }
}

$hex = $namedColor::toHex();
if (!preg_match('/^#?([a-f\d]{3}|[a-f\d]{4}|[a-f\d]{6}|[a-f\d]{8})$/i', $hex)) {
    throw new \RuntimeException('NamedColor::toHex() must return valid hex, got: ' . $hex);
}
$rgb = $namedColor->toColorspace(\Intervention\Image\Colors\Rgb\Colorspace::class);

try {
    $rgb = $namedColor->toColorspace(\Intervention\Image\Colors\Rgb\Colorspace::class);
} catch (\Intervention\Image\Exceptions\ColorException $e) {
    $previous = $e->getPrevious(); // hex decode failure details
    $rgb = \Intervention\Image\Colors\Rgb\Color::fromHex('ff0000'); // safe fallback
}

When it happens

Trigger: 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().

Common situations: 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.

Related errors

• Failed to import color {colorClass} to {class}
• Unable to import color {colorClass} to {class}
• Failed to import color {colorClass} to {class}
• Unable to import color {color_class} to {colorspace_class}
• Failed to import color {color_class} to {colorspace_class}

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