Intervention/image · error · InvalidArgumentException

GD driver can only decode array color format array{red: int,

Error message

GD driver can only decode array color format array{red: int, green: int, blue: int, alpha: int}

What it means

import() accepted that the value is an array, but isValidArrayColor() (src/Drivers/Gd/ColorProcessor.php:120) requires all four integer keys red, green, blue, alpha with int values — exactly the shape imagecolorsforindex() returns. Missing keys, differently-named keys (r/g/b/a), or string values fail this check.

Source

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

    /**
     * {@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;
            $g = ($color >> 8) & 0xFF;
            $b = $color & 0xFF;
        }

        try {
            // convert gd apha integer to intervention alpha integer

View on GitHub (pinned to 5598b9e397)

Solutions

1. Normalize keys and cast to int before importing: array_map(fn($v) => (int) $v, ['red' => $c['r'], 'green' => $c['g'], 'blue' => $c['b'], 'alpha' => $c['a'] ?? 0])
2. Feed import() exclusively with the untouched output of imagecolorsforindex($gd, $index)
3. For hex/array user input, prefer Color::create() which accepts more shapes

Example fix

// before
$color = $processor->import(['r' => 255, 'g' => 0, 'b' => 0]);

// after
$color = $processor->import([
    'red' => 255, 'green' => 0, 'blue' => 0, 'alpha' => 0,
]);

/** @param array<mixed> $color */
function isGdColorArray(array $color): bool
{
    foreach (['red', 'green', 'blue', 'alpha'] as $key) {
        if (!array_key_exists($key, $color) || !is_int($color[$key])) {
            return false;
        }
    }

    return true;
}

use Intervention\Image\Exceptions\InvalidArgumentException;

try {
    $color = $processor->import($array);
} catch (InvalidArgumentException $e) {
    $color = new Intervention\Image\Colors\Rgb\Color(
        (int) ($array['red'] ?? $array['r'] ?? 0),
        (int) ($array['green'] ?? $array['g'] ?? 0),
        (int) ($array['blue'] ?? $array['b'] ?? 0),
        0,
    );
}

When it happens

Trigger: Passing ['r' => 255, 'g' => 0, 'b' => 0, 'a' => 0]; passing ['red' => '255', ...] with string values from a database/JSON; arrays missing the alpha entry (e.g. hand-built 3-element RGB).

Common situations: Persisted color arrays from other libraries or user settings stored as JSON; arrays built by array_map('strval', ...) pipelines; partial arrays copied from documentation snippets.

Related errors

• GD driver can only decode colors in integer or array format
• Failed to import color
• Invalid cmyk() color syntax "{input}"
• Unable to parse HSL color from input "{input}"
• Invalid hsl() color syntax "{input}"

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