{"record":{"id":"eebee891e50320cd","repo":"Intervention/image","slug":"failed-to-normalize-background-color-to-rgb-color-eebee8","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/RotateModifier.php","lineNumber":60,"sourceCode":"\n        return $image;\n    }\n\n    /**\n     * Apply rotation modification on given frame, given background\n     * color is used for newly create image areas\n     *\n     * @throws InvalidArgumentException\n     * @throws ModifierException\n     * @throws DriverException\n     */\n    protected function modifyFrame(FrameInterface $frame, ColorInterface $background): void\n    {\n        // normalize color to rgb colorspace\n        $background = $background->toColorspace(Rgb::class);\n\n        if (!$background instanceof RgbColor) {\n            throw new ModifierException('Failed to normalize background color to RGB color space');\n        }\n\n        // get transparent color from frame core\n        $transparent = match ($transparent = imagecolortransparent($frame->native())) {\n            -1 => imagecolorallocatealpha(\n                $frame->native(),\n                $background->red()->value(),\n                $background->green()->value(),\n                $background->blue()->value(),\n                127,\n            ),\n            default => $transparent,\n        };\n\n        // rotate original image against transparent background\n        $rotated = imagerotate(\n            $frame->native(),\n            $this->rotationAngle() * -1,","sourceCodeStart":42,"sourceCodeEnd":78,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Drivers/Gd/Modifiers/RotateModifier.php#L42-L78","documentation":"Rotating by non-right angles creates new corner areas that are filled with a background color. The GD driver converts the background (the rotate() argument or the configured default) with toColorspace(Rgb\\Colorspace::class) per frame and requires an Rgb\\Color before calling imagerotate(). Built-in colors always satisfy this; only custom ColorInterface implementations that do not convert to RGB trigger the exception.","triggerScenarios":"$image->rotate(45, $customColorObject) where the object does not convert to Rgb\\Color; rotate() with no background argument while a custom Config->backgroundColor object of that kind is set.","commonSituations":"Custom color classes or color-token objects passed into rotation pipelines; code shared between drivers that carries driver-specific color objects.","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() return an Rgb\\Color","Catch ModifierException and retry with a known-good color"],"exampleFix":"// before\n$image->rotate(45, $customColorObject);\n\n// after: opaque RGB string background for the new corners\n$image->rotate(45, 'ffffff');","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('Rotation background does not convert to Rgb\\Color');\n}\n\n$image->rotate(45, $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->rotate(45, $background);\n} catch (ModifierException $e) {\n    $image->rotate(45, 'ffffff');\n}","preventionTips":["Pass opaque RGB strings or Rgb\\Color instances as rotation backgrounds.","Verify custom color objects convert to RGB before sharing them across drivers."],"tags":["gd","rotate","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"}