Intervention/image · error · DriverException

Failed to import color

Error message

Failed to import color

What it means

After extracting r/g/b and the GD alpha (0-127) from the int or array input, import() remaps alpha to [0..1] with convertRange($a, 127, 0, 0, 1). That helper only throws RuntimeException on a degenerate range (division by zero when min == max, src/Traits/CanConvertRange.php:27-28); with the fixed constants 127 and 0 it cannot. This DriverException is therefore a defensive, effectively unreachable guard kept to wrap any future range failure.

Source

Thrown at src/Drivers/Gd/ColorProcessor.php:103

            $r = $color['red'];
            $g = $color['green'];
            $b = $color['blue'];
            $a = $color['alpha'];
        } else {
            // integer conversion
            $a = ($color >> 24) & 0xFF;
            $r = ($color >> 16) & 0xFF;
            $g = ($color >> 8) & 0xFF;
            $b = $color & 0xFF;
        }

        try {
            // convert gd apha integer to intervention alpha integer
            // ([opaque]0-127[transparent]) to ([opaque]1-0[transparent])
            $a = self::convertRange($a, 127, 0, 0, 1);
        } catch (RuntimeException $e) {
            throw new DriverException('Failed to import color', previous: $e);
        }

        try {
            return new Color($r, $g, $b, $a);
        } catch (InvalidArgumentException $e) {
            throw new DriverException('Failed to import color', previous: $e);
        }
    }

    /**
     * Check if given array is valid color format
     * array{red: int, green: int, blue: int, alpha: int}
     * i.e. result of imagecolorsforindex()
     *
     * @param array<mixed> $color
     */
    private function isValidArrayColor(array $color): bool
    {

View on GitHub (pinned to 5598b9e397)

Solutions

1. If you encounter it, check that vendor/intervention/image is unmodified: composer validate && composer install --prefer-source to diff
2. Report it upstream with a reproducer, since stock code paths cannot trigger it
3. Handle like any DriverException: catch, log ->getPrevious() for the wrapped RuntimeException

use Intervention\Image\Exceptions\DriverException;

try {
    $color = $processor->import($gdValue);
} catch (DriverException $e) {
    // unreachable in stock code; check vendor integrity if this fires
    throw $e;
}

When it happens

Trigger: Not reproducible through the public import() with any int or valid-shape array input; a theoretical guard only meaningful for library maintainers or forks that alter the constants.

Common situations: Appears only in test suites enumerating every documented @throws branch; users seeing it should suspect a patched/forked vendor directory.

Related errors

• Failed to export color
• GD driver can only decode colors in integer or array format
• GD driver can only decode array color format array{red: int,
• Failed to invert color
• Failed to import color {colorClass} to {class}

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