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

Unknown color space ({colorspace}) as conversion target

Error message

Unknown color space ({colorspace}) as conversion target

What it means

Font::setAlignmentVertical() is the vertical counterpart: strings must exactly match an Alignment enum backing value ('top', 'center', 'bottom', or the diagonals like 'top-left'); everything else makes Alignment::from() throw, which the setter converts into InvalidArgumentException('Invalid value for alignment'). It is reached through FontFactory::align(null, $vertical) or direct font configuration.

Source

Thrown at src/Colors/AbstractColor.php:73

        if (count($channels) === 0) {
            throw new InvalidArgumentException('Color channel ' . $classname . ' could not be found');
        }

        return reset($channels);
    }

    /**
     * {@inheritdoc}
     *
     * @see ColorInterface::toColorspace()
     *
     * @throws InvalidArgumentException
     */
    public function toColorspace(string|ColorspaceInterface $colorspace): ColorInterface
    {
        if (is_string($colorspace) && !class_exists($colorspace)) {
            throw new InvalidArgumentException('Unknown color space (' . $colorspace . ') as conversion target');
        }

        $colorspace = is_string($colorspace) ? new $colorspace() : $colorspace;

        if (!$colorspace instanceof ColorspaceInterface) {
            throw new InvalidArgumentException('Given color space must implement ' . ColorspaceInterface::class);
        }

        return $colorspace->importColor($this);
    }

    /**
     * {@inheritdoc}
     *
     * @see ColorInterface::isTransparent()
     */
    public function isTransparent(): bool
    {

View on GitHub (pinned to 5598b9e397)

Solutions

1. Use the exact lowercase values: 'top', 'center', 'bottom' (or diagonal cases if combined)
2. Sanitize external input: strtolower() + str_replace(['_', ' '], '-', $value), and whitelist against ['top', 'center', 'bottom']
3. Pass Alignment::TOP / Alignment::CENTER / Alignment::BOTTOM enum instances to avoid string pitfalls entirely

Example fix

// before
$font->align(null, 'MIDDLE'); // case-sensitive from() -> throws

// after
$font->align(null, 'middle'); // or Alignment::MIDDLE does not exist; use:
$font->align(null, \Intervention\Image\Alignment::CENTER);

use Intervention\Image\Alignment;

$value = strtolower(trim((string) $input));
if (!in_array($value, ['top', 'center', 'bottom'], true)) {
    $value = 'center'; // or reject
}
$font->align(null, $value);

use Intervention\Image\Alignment;

function toVerticalAlignment(string $value): Alignment
{
    return match (strtolower($value)) {
        'top' => Alignment::TOP,
        'bottom' => Alignment::BOTTOM,
        'center', 'middle' => Alignment::CENTER,
        default => throw new \InvalidArgumentException('Invalid vertical alignment: ' . $value),
    };
}

use Intervention\Image\Exceptions\InvalidArgumentException;

try {
    $font->align(null, $vertical);
} catch (InvalidArgumentException $e) {
    if (str_contains($e->getMessage(), 'alignment')) {
        $font->align(null, 'center'); // safe default
    }
}

When it happens

Trigger: $font->align(null, 'middle') or 'baseline' (not enum values); 'TOP' or 'Top' with wrong casing; underscore forms like 'bottom_center'; vertical values coming from a UI dropdown that uses different vocabulary ('top-edge', 'flow-root').

Common situations: CSS vertical-align vocabulary ('middle', 'baseline', 'sub') reused for image text; snake_case values from JavaScript front-ends; localized strings; config files written before the exact allowed set was known.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Color channel {classname} could not be found
• Unable to parse RGB color from input "{input}"
• Invalid $limit value. Must be int<1, max>
• Call to undefined method Intervention\Image\Image::{name}()
• Argument $extension must not be an empty string

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