{"record":{"id":"8e836ed70b87abd0","repo":"Intervention/image","slug":"failed-to-normalize-background-color-to-rgb-color-8e836e","errorCode":null,"errorMessage":"Failed to normalize background color to RGB color space","messagePattern":"Failed to normalize background color to RGB color space","errorType":"exception","errorClass":"ModifierException","httpStatus":null,"severity":"error","filePath":"src/Drivers/Gd/Modifiers/CropModifier.php","lineNumber":39,"sourceCode":"{\n    /**\n     * {@inheritdoc}\n     *\n     * @see ModifierInterface::apply()\n     *\n     * @throws InvalidArgumentException\n     * @throws ModifierException\n     * @throws StateException\n     * @throws DriverException\n     */\n    public function apply(ImageInterface $image): ImageInterface\n    {\n        $originalSize = $image->size();\n        $crop = $this->crop($image);\n        $background = $this->backgroundColor()->toColorspace(RgbColorspace::class);\n\n        if (!$background instanceof RgbColor) {\n            throw new ModifierException('Failed to normalize background color to RGB color space');\n        }\n\n        foreach ($image as $frame) {\n            $this->cropFrame($frame, $originalSize, $crop, $background);\n        }\n\n        return $image;\n    }\n\n    /**\n     * @throws InvalidArgumentException\n     * @throws ModifierException\n     * @throws DriverException\n     */\n    private function cropFrame(\n        FrameInterface $frame,\n        SizeInterface $originalSize,\n        SizeInterface $resizeTo,","sourceCodeStart":21,"sourceCodeEnd":57,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Drivers/Gd/Modifiers/CropModifier.php#L21-L57","documentation":"crop() cuts a rectangle out of the image; when the requested crop is larger than the source, the areas outside the original are filled with a background color. The GD implementation converts that color (argument or the configured default) to the RGB colorspace and requires an Intervention\\Image\\Colors\\Rgb\\Color before cropping each frame. All built-in colors and color strings convert cleanly, so the exception is reserved for custom ColorInterface implementations whose toColorspace(Rgb\\Colorspace::class) does not return an Rgb\\Color.","triggerScenarios":"Calling $image->crop($w, $h, $x, $y, $customColorObject) where the object does not convert to Rgb\\Color; cropping without an explicit background while a custom Config->backgroundColor object of that kind is active.","commonSituations":"Extending the library with custom color/colorspace classes; passing third-party color objects into the background parameter; pipelines migrated between drivers that carry driver-specific color objects.","solutions":["Pass a standard color value: '#ff0000', 'rgb(255, 0, 0)', a named color, or an Intervention\\Image\\Colors\\Rgb\\Color instance","Make your custom color's toColorspace(Rgb\\Colorspace::class) return an Rgb\\Color","Convert the color yourself before calling crop(): $custom->toColorspace(Rgb\\Colorspace::class)","Catch ModifierException and retry with a known-good fallback color"],"exampleFix":"// before\n$image->crop(500, 500, 0, 0, $customColorObject);\n\n// after: oversized crop filled with a plain RGB color\nuse Intervention\\Image\\Colors\\Rgb\\Color;\n$image->crop(500, 500, 0, 0, new Color(255, 255, 255));","handlingStrategy":"type-guard","validationCode":"use Intervention\\Image\\Colors\\Rgb\\Color as RgbColor;\nuse Intervention\\Image\\Colors\\Rgb\\Colorspace as RgbColorspace;\nuse Intervention\\Image\\Interfaces\\ColorInterface;\n\n$background = $color instanceof ColorInterface\n    ? $color->toColorspace(RgbColorspace::class)\n    : $color;\n\nif (!$background instanceof RgbColor) {\n    throw new LogicException('Background color does not convert to Rgb\\Color');\n}\n\n$image->crop(500, 500, 0, 0, $background);","typeGuard":"function isGdSafeBackground(string|ColorInterface $color): bool\n{\n    return is_string($color)\n        || $color->toColorspace(RgbColorspace::class) instanceof RgbColor;\n}","tryCatchPattern":"use Intervention\\Image\\Exceptions\\ModifierException;\n\ntry {\n    $image->crop(500, 500, 0, 0, $background);\n} catch (ModifierException $e) {\n    $image->crop(500, 500, 0, 0, 'ffffff');\n}","preventionTips":["Pass hex/rgb strings or Rgb\\Color instances as crop backgrounds.","Test custom color classes against toColorspace(Rgb\\Colorspace::class) instanceof Rgb\\Color.","Do not share Imagick-specific color objects with GD pipelines."],"tags":["gd","crop","background-color","colorspace","rgb"],"backgroundTag":"colorspace-conversion-failed","analyzedSha":"5598b9e39751c34afc5cdee84abef77f92c26f68","analyzedAt":"2026-08-23T02:17:31.068Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}