Intervention/image · error · InvalidArgumentException

GD driver can only decode colors in integer or array format

Error message

GD driver can only decode colors in integer or array format

What it means

The GD color processor's import() only accepts two physical GD representations: an int (packed RGBA) or the array shape returned by imagecolorsforindex(). Any other type — string, null, object — is rejected up front. This is a type-contract error: the method is meant to unwrap GD natives, not to parse human color notations.

Source

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

        } catch (RuntimeException $e) {
            throw new DriverException('Failed to export color', previous: $e);
        }

        return ($a << 24) + ($r << 16) + ($g << 8) + $b;
    }

    /**
     * {@inheritdoc}
     *
     * @see ColorProcessorInterface::import()
     *
     * @throws InvalidArgumentException
     * @throws DriverException
     */
    public function import(mixed $color): ColorInterface
    {
        if (!is_int($color) && !is_array($color)) {
            throw new InvalidArgumentException('GD driver can only decode colors in integer or array format');
        }

        if (is_array($color)) {
            // array conversion
            if (!$this->isValidArrayColor($color)) {
                throw new InvalidArgumentException(
                    'GD driver can only decode array color format array{red: int, green: int, blue: int, alpha: int}',
                );
            }

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

View on GitHub (pinned to 5598b9e397)

Solutions

1. To build a Color from a string, use the Color class itself: Color::create('ff0000') — not the processor
2. Pass only values obtained from GD (imagecolorat() int or imagecolorsforindex() array) into import()
3. For driver-agnostic code, go through $manager->createDriver()->colorProcessor() only with native values you got from the same driver

Example fix

// before
$color = $gdDriver->colorProcessor()->import('#ff0000');

// after
use Intervention\Image\Colors\Rgb\Color;

$color = Color::create('#ff0000'); // string parsing belongs to Color
$gdColor = $gdDriver->colorProcessor()->import(imagecolorat($gd, 10, 10));

/** @param mixed $color */
function isGdImportable(mixed $color): bool
{
    return is_int($color) || is_array($color);
}

use Intervention\Image\Exceptions\InvalidArgumentException;

try {
    $color = $processor->import($value);
} catch (InvalidArgumentException $e) {
    $color = Intervention\Image\Colors\Rgb\Color::create((string) $value); // parse strings via Color
}

When it happens

Trigger: Calling $driver->colorProcessor()->import('ff0000'), import(null), or import($colorObject); passing a hex string or an Intervention Color where a GD-native value was expected.

Common situations: Developers assuming import() is a generic color parser; wiring data from JSON configs (strings) straight into the driver API; adapter code ported from other libraries whose import() accepts strings.

Related errors

• GD driver can only decode array color format array{red: int,
• Failed to import color
• Invalid cmyk() color syntax "{input}"
• Unable to parse HSL color from input "{input}"
• 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/afb92eece9fe46dc. Report an issue: GitHub.