Intervention/image · error · ColorDecoderException

Unknown color format

Error message

Unknown color format

What it means

The driver ran the full color decoder chain (hex strings, rgb()/rgba() strings, integer color values, named colors, 'transparent', and ColorInterface objects) and none could decode the input. The NotSupportedException from the chain is converted into this ColorDecoderException, so any color in a format the library does not speak produces it.

Source

Thrown at src/Drivers/AbstractDriver.php:96

     *
     * @see DriverInterface::decodeColor()
     *
     * @throws InvalidArgumentException
     * @throws ColorDecoderException
     * @throws DriverException
     */
    public function decodeColor(mixed $input, ?array $decoders = null): ColorInterface
    {
        $decoders = $decoders === null ? InputHandler::COLOR_DECODERS : $decoders;

        if (count($decoders) === 0) {
            throw new InvalidArgumentException('No decoders in array');
        }

        try {
            $result = InputHandler::usingDecoders($decoders, $this)->handle($input);
        } catch (NotSupportedException) {
            throw new ColorDecoderException('Unknown color format');
        }

        if (!$result instanceof ColorInterface) {
            throw new ColorDecoderException('Result must be instance of ' . ColorInterface::class);
        }

        return $result;
    }

    /**
     * {@inheritdoc}
     *
     * @see DriverInterface::specializeModifier()
     *
     * @throws NotSupportedException
     */
    public function specializeModifier(ModifierInterface $modifier): ModifierInterface
    {

View on GitHub (pinned to 5598b9e397)

Solutions

1. Convert the color to a supported format first - hex ('#ff0000') or rgb()/rgba() syntax - or use NamedColor/transparent
2. Validate user-provided colors at the input boundary and substitute a default when they do not match a supported format
3. If you need HSL/CMYK input, convert it to RGB yourself before passing it to the library

Example fix

// before
$img->fill($userColor); // e.g. 'hsl(120, 50%, 50%)'

// after
$safe = validate_color($userColor) ?: '#ffffff';
$img->fill($safe);

function isSupportedColorString(string $value): bool
{
    return preg_match('/^(#(?:[0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})|rgba?\(.+\)|transparent|[a-z]+)$/i', $value) === 1;
}

try {
    $img->fill($userColor);
} catch (ColorDecoderException $e) {
    $img->fill('#ffffff');
}

When it happens

Trigger: fill('cmyk(0, 84, 100, 0)'), ->color('hsl(120, 50%, 50%)'), a misspelled name like 'rd', null, or a float like 12.5 passed to any color-accepting API (fill(), textColor(), backgroundColor, pickColor consumers).

Common situations: User- or CMS-entered colors with typos; CSS color functions the library does not support (hsl(), cmyk(), color()); values that are null because an upstream lookup failed.

Related errors

• Color object must be of type {ColorInterface::class}
• Base64-encoded data must be either of type string or instanc
• Result must be instance of {ColorInterface::class}
• Unsupported media type (MIME) ${mediaType}.
• Unsupported media type (MIME) ${mime}.

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