{"record":{"id":"bc4a81a4ed25d77e","repo":"Intervention/image","slug":"failed-to-convert-background-color-to-rgb-color-sp","errorCode":null,"errorMessage":"Failed to convert background color to RGB color space","messagePattern":"Failed to convert background color to RGB color space","errorType":"exception","errorClass":"ModifierException","httpStatus":null,"severity":"error","filePath":"src/Drivers/Gd/Modifiers/ReduceColorsModifier.php","lineNumber":46,"sourceCode":"     */\n    public function apply(ImageInterface $image): ImageInterface\n    {\n        if ($this->limit <= 0) {\n            throw new InvalidArgumentException('Quantization limit must be greater than 0');\n        }\n\n        // no color reduction if the limit is higher than the colors in the img\n        $colorCount = imagecolorstotal($image->core()->native());\n        if ($colorCount > 0 && $this->limit > $colorCount) {\n            return $image;\n        }\n\n        $width = $image->width();\n        $height = $image->height();\n        $backgroundColor = $this->backgroundColor($image);\n\n        if (!$backgroundColor instanceof RgbColor) {\n            throw new ModifierException('Failed to convert background color to RGB color space');\n        }\n\n        $nativeBackgroundColor = $this->driver()\n            ->colorProcessor($image)\n            ->export($backgroundColor);\n\n        foreach ($image as $frame) {\n            // create new image for color quantization\n            $reduced = Cloner::cloneEmpty($frame->native(), background: $backgroundColor);\n\n            // fill with background\n            imagefill($reduced, 0, 0, $nativeBackgroundColor);\n\n            // set transparency\n            imagecolortransparent($reduced, $nativeBackgroundColor);\n\n            // copy original image (colors are limited automatically in the copy process)\n            imagecopy($reduced, $frame->native(), 0, 0, 0, 0, $width, $height);","sourceCodeStart":28,"sourceCodeEnd":64,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Drivers/Gd/Modifiers/ReduceColorsModifier.php#L28-L64","documentation":"Before quantizing, reduceColors() fills transparent areas with a background color and exports it to a GD palette index. The GD implementation resolves $background ?? config backgroundColor (default 'ffffff'), converts it to the image's colorspace and requires the result to be an Intervention\\Image\\Colors\\Rgb\\Color. All built-in colors and color strings convert cleanly, so the exception is reserved for custom ColorInterface implementations whose colorspace conversion does not produce an Rgb\\Color.","triggerScenarios":"$image->reduceColors(64, $customColorObject) where the object does not convert to Rgb\\Color; calling reduceColors() without an explicit background while a custom Config->backgroundColor object of that kind is set.","commonSituations":"Custom color system or decoder extensions; brand palettes injected as color objects; config-driven background colors shared across multiple libraries.","solutions":["Pass a standard color value: '#ffffff', 'rgb(255, 255, 255)', a named color, or an Intervention\\Image\\Colors\\Rgb\\Color instance","Convert your custom color first: $custom->toColorspace(Rgb\\Colorspace::class)","Make your custom color's toColorspace(Rgb\\Colorspace::class) return an Rgb\\Color","Catch ModifierException and retry with a known-good color"],"exampleFix":"// before\n$image->reduceColors(64, $customColorObject);\n\n// after\nuse Intervention\\Image\\Colors\\Rgb\\Color;\n$image->reduceColors(64, 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->reduceColors(64, $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->reduceColors(64, $background);\n} catch (ModifierException $e) {\n    $image->reduceColors(64, 'ffffff');\n}","preventionTips":["Pass hex/rgb strings or Rgb\\Color instances as the reduceColors() background.","Test custom color classes for RGB conversion before using them in config defaults.","Keep limit >= 1 at the same time - both guards protect this call."],"tags":["gd","reduce-colors","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"}