phalcon/cphalcon · error · Phalcon\Image\Exceptions\InvalidColor

The color '{color}' is not a valid hex color

Error message

The color '{color}' is not a valid hex color

What it means

The adapter's hex-color parser (used for background(), rotate() and text colors) accepts only 'rgb', '#rgb', 'rrggbb' and '#rrggbb': it strips a leading '#', doubles 3-character forms, then requires the result to match ^[0-9a-fA-F]{6}$ - otherwise InvalidColor is thrown. CSS color names, rgba(), 8-digit hex and other formats are not supported.

Source

Thrown at phalcon/Image/Adapter/AbstractAdapter.zep:634

     * @throws InvalidColor
     */
    private function parseColor(string color) -> array
    {
        var channels;

        if (
            strlen(color) > 1 &&
            substr(color, 0, 1) === "#"
        ) {
            let color = substr(color, 1);
        }

        if (strlen(color) === 3) {
            let color = (string) preg_replace("/./", "$0$0", color);
        }

        if (1 !== preg_match("/^[0-9a-fA-F]{6}$/", color)) {
            throw new InvalidColor(color);
        }

        /** @var image_color_channels $channels */
        let channels = array_map(
            "hexdec",
            str_split(color, 2)
        );

        return channels;
    }
}

View on GitHub (pinned to b7419de9cd)

Solutions

1. Validate before calling: preg_match('/^#?([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/', $color)
2. Map CSS names to hex yourself ('white' => 'ffffff') or store canonical '#rrggbb' values
3. Trim and normalize user input before passing it to the adapter

Example fix

// before
$image->background('white'); // names not supported -> throws

// after
$map = ['white' => 'ffffff', 'black' => '000000'];
$color = $map[$requested] ?? $requested;
if (!preg_match('/^#?([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/', $color)) {
    throw new InvalidArgumentException('Invalid color: ' . $requested);
}
$image->background($color);

$color = trim((string) $color);
if (!preg_match('/^#?([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/', $color)) {
    throw new \InvalidArgumentException(sprintf('"%s" is not a valid hex color', $color));
}
$image->background(ltrim($color, '#'));

function isHexColor(mixed $color): bool
{
    return is_string($color) && 1 === preg_match('/^#?([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/', trim($color));
}

try { $image->background($color); } catch (\Phalcon\Image\Exceptions\InvalidColor $e) { $image->background('ffffff'); // safe default
}

When it happens

Trigger: ->background('white'); ->rotate(45, 'zz12ab'); a color string from user input containing whitespace, quotes or a wrong length such as '#12ab'.

Common situations: Passing CSS color names instead of hex; free-text color fields saved from forms or databases without validation; alpha-suffixed colors like '#aabbccdd' which fail the 6-hex rule.

Related errors

• Width and height must be specified
• Width must be specified
• Height must be specified
• Unable to insert into {table} without data
• The number of values in the update is not the same as fields

AI-assisted analysis of phalcon/cphalcon@b7419de9cd (2026-08-21). Data as JSON: /api/errors/6ac35bc33d3ef4d6. Report an issue: GitHub.