Intervention/image · error · Intervention\Image\Exceptions\InvalidArgumentException

Unable to parse HSL color from input "{input}"

Error message

Unable to parse HSL color from input "{input}"

What it means

Hsl\Color::parse() only accepts strings decodable by the HSL string color decoder, which requires the input to start with 'hsl' (e.g. 'hsl(0, 100%, 50%)' or 'hsla(0, 100%, 50% / 0.5)'). When no registered decoder can handle the input, the resulting NotSupportedException/DriverException is wrapped in this InvalidArgumentException repeating the offending input. Note: a string that starts with 'hsl' but is malformed throws the different error 'Invalid hsl() color syntax'.

Source

Thrown at src/Colors/Hsl/Color.php:64

    public static function create(int|Hue $h, int|Saturation $s, int|Luminance $l, float|Alpha $a = 1): self
    {
        return new self($h, $s, $l, $a);
    }

    /**
     * Parse HSL color from string.
     *
     * @throws InvalidArgumentException
     * @throws ColorException
     */
    public static function parse(string $input): self
    {
        try {
            $color = InputHandler::usingDecoders([
                StringColorDecoder::class,
            ])->handle($input);
        } catch (NotSupportedException | DriverException $e) {
            throw new InvalidArgumentException(
                'Unable to parse HSL color from input "' . $input . '"',
                previous: $e,
            );
        }

        if (!$color instanceof self) {
            throw new ColorException('Result must be instance of ' . self::class);
        }

        return $color;
    }

    /**
     * {@inheritdoc}
     *
     * @see ColorInterface::colorspace()
     */
    public function colorspace(): ColorspaceInterface

View on GitHub (pinned to 5598b9e397)

Solutions

1. Pass HSL syntax: Hsl\Color::parse('hsl(0, 100%, 50%)')
2. For hex/rgb/named input, parse with Rgb\Color::parse() (or the generic color parser) and convert: $color->toColorspace(Hsl\Colorspace::class)
3. Trim the input before parsing: Hsl\Color::parse(trim($input))
4. If accepting arbitrary user input, validate the prefix and fall back to a default color instead of failing

Example fix

// before
$hsl = Hsl\Color::parse('#ff0000');

// after
$hsl = Rgb\Color::parse('#ff0000')->toColorspace(Hsl\Colorspace::class);
// or use correct syntax directly:
$hsl = Hsl\Color::parse('hsl(0, 100%, 50%)');

$trimmed = trim((string) $input);
if (!str_starts_with(strtolower($trimmed), 'hsl')) {
    // not parseable by Hsl\Color::parse(); route hex/rgb via Rgb\Color::parse()
}

function isHslParseable(mixed $input): bool
{
    return is_string($input) && str_starts_with(strtolower(trim($input)), 'hsl');
}

use Intervention\Image\Exceptions\InvalidArgumentException as ImageArg;

try {
    $hsl = Hsl\Color::parse($input);
} catch (ImageArg $e) {
    $hsl = Rgb\Color::parse($input)->toColorspace(Hsl\Colorspace::class);
}

When it happens

Trigger: Hsl\Color::parse('#ff0000'), Hsl\Color::parse('rgb(255, 0, 0)'), Hsl\Color::parse('red'), Hsl\Color::parse('') - none start with 'hsl', so the decoder's supports() check fails and the InputHandler throws, which parse() wraps. Also non-string or whitespace-padded input.

Common situations: Storing colors as hex/RGB in a database or config and passing them to the HSL-specific parser; generic user input funneled into a colorspace-specific parse method; whitespace or BOM prefixes from templates or CSV files.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Invalid hsl() color syntax "{input}"
• Invalid cmyk() color syntax "{input}"
• Unable to parse HSV color from input "{input}"
• Number of color channels must be 3 or 4 for {class}
• 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/adac51aa8586def1. Report an issue: GitHub.