Intervention/image · error · Intervention\Image\Exceptions\ColorException

Failed to import color {color_class} to {colorspace_class}

Error message

Failed to import color {color_class} to {colorspace_class}

What it means

This ColorException wraps an InvalidArgumentException raised while constructing the OKLAB color during an RGB to OKLAB conversion (src/Colors/Oklab/Colorspace.php:116-128). The matrix math maps normalized RGB into lightness (0..1) and a/b axes (-0.4..0.4); a channel constructor only rejects values outside those bounds, so with a healthy RgbColor this is a defensive path that should not fire.

Source

Thrown at src/Colors/Oklab/Colorspace.php:124

        $b = $rgbToLinear($b);

        $l = 0.4122214708 * $r + 0.5363325363 * $g + 0.0514459929 * $b;
        $m = 0.2119034982 * $r + 0.6806995451 * $g + 0.1073969566 * $b;
        $s = 0.0883024619 * $r + 0.2817188376 * $g + 0.6299787005 * $b;

        $l = $cbrt($l);
        $m = $cbrt($m);
        $s = $cbrt($s);

        try {
            return new Color(
                0.2104542553 * $l + 0.7936177850 * $m - 0.0040720468 * $s,
                1.9779984951 * $l - 2.4285922050 * $m + 0.4505937099 * $s,
                0.0259040371 * $l + 0.7827717662 * $m - 0.8086757660 * $s,
                $color->alpha()->normalized(),
            );
        } catch (InvalidArgumentException $e) {
            throw new ColorException(
                'Failed to import color ' . $color::class . ' to ' . $this::class,
                previous: $e,
            );
        }
    }

    /**
     * Import given OKLCH color OKLAB colorspace.
     *
     * @throws ColorException
     */
    private function importOklchColor(OklchColor $color): OklabColor
    {
        $hRad = deg2rad($color->hue()->value());

        try {
            return new Color(
                $color->lightness()->value(),

View on GitHub (pinned to 5598b9e397)

Solutions

1. Inspect getPrevious() to see which channel and range was violated
2. Verify the source RGB color's channels: $color->red()->normalized() must be within 0..1
3. Rebuild the color from known-good values (e.g. re-parse from hex) and retry
4. If reproducible with plain valid colors, file a library bug including both channel values

Example fix

// before
$oklab = $rgb->toColorspace(Oklab\Colorspace::class); // ColorException: Failed to import color ...

// after
// ensure the source color is well-formed, then convert
$rgb = Rgb\Color::create($r, $g, $b); // re-validated 0..255 values
$oklab = $rgb->toColorspace(Oklab\Colorspace::class);

// Guard the source color's normalized channels before converting
$channels = [$rgb->red(), $rgb->green(), $rgb->blue()];
foreach ($channels as $ch) {
    if ($ch->normalized() < 0.0 || $ch->normalized() > 1.0) {
        // rebuild the color from known-good values before converting
    }
}

function hasNormalizedRgbChannels(RgbColor $color): bool
{
    foreach ([$color->red(), $color->green(), $color->blue()] as $ch) {
        $n = $ch->normalized();
        if ($n < 0.0 || $n > 1.0) { return false; }
    }
    return true;
}

try {
    $oklab = $rgb->toColorspace(Oklab\Colorspace::class);
} catch (ColorException $e) {
    // practically an internal error: log getPrevious() and rebuild the source color
}

When it happens

Trigger: Converting an RgbColor whose channels report normalized values outside 0..1 (possible with a corrupted or custom channel object) via $rgb->toColorspace(Oklab\Colorspace::class), producing computed OKLAB coordinates beyond the channel limits.

Common situations: Almost exclusively an internal/edge failure: corrupted color objects, custom channel implementations violating bounds, or numerical drift from non-standard channel min/max overrides; not caused by normal usage.

Related errors

• Unable to import color {color_class} to {colorspace_class}
• Failed to import color {color_class} to {colorspace_class}
• Unable to parse OKLAB color from input "{input}"
• Number of color channels must be 3 or 4 for {class}
• Normalized color value must be in range 0 to 1

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