{"record":{"id":"422f37237f093019","repo":"Intervention/image","slug":"failed-to-export-color","errorCode":null,"errorMessage":"Failed to export color","messagePattern":"Failed to export color","errorType":"exception","errorClass":"DriverException","httpStatus":null,"severity":"error","filePath":"src/Drivers/Gd/ColorProcessor.php","lineNumber":58,"sourceCode":"     * @throws DriverException\n     */\n    public function export(ColorInterface $color): int\n    {\n        // convert color to colorspace\n        $color = $color->toColorspace($this->colorspace());\n\n        // gd only supports rgb so the channels can be accessed directly\n        $r = $color->channel(Red::class)->value();\n        $g = $color->channel(Green::class)->value();\n        $b = $color->channel(Blue::class)->value();\n        $a = $color->channel(Alpha::class)->value();\n\n        try {\n            // convert alpha value to gd alpha\n            // ([opaque]1-0[transparent]) to ([opaque]0-127[transparent])\n            $a = (int) round(self::convertRange($a, Alpha::min(), Alpha::max(), 127, 0));\n        } catch (RuntimeException $e) {\n            throw new DriverException('Failed to export color', previous: $e);\n        }\n\n        return ($a << 24) + ($r << 16) + ($g << 8) + $b;\n    }\n\n    /**\n     * {@inheritdoc}\n     *\n     * @see ColorProcessorInterface::import()\n     *\n     * @throws InvalidArgumentException\n     * @throws DriverException\n     */\n    public function import(mixed $color): ColorInterface\n    {\n        if (!is_int($color) && !is_array($color)) {\n            throw new InvalidArgumentException('GD driver can only decode colors in integer or array format');\n        }","sourceCodeStart":40,"sourceCodeEnd":76,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Drivers/Gd/ColorProcessor.php#L40-L76","documentation":"GD's ColorProcessor::export() converts an Intervention Color to a single GD integer, remapping the alpha channel from [0..1] to [127..0] via CanConvertRange::convertRange(). That helper only throws RuntimeException on a degenerate range (min == max, division by zero at src/Traits/CanConvertRange.php:27-28). With the built-in Rgb\\Color the alpha range is always 0..1, so in practice this DriverException is a defensive wrapper reachable mainly through custom ColorInterface implementations whose channel() values are inconsistent.","triggerScenarios":"Passing a hand-rolled ColorInterface class into $gdDriver->colorProcessor()->export($color) whose Alpha channel reports identical min()/max() (e.g. both 0); none of the standard library colors can trigger it.","commonSituations":"Extending the color system with custom color classes (brand palettes, exotic colorspaces) and feeding them to GD-driver text drawing or fills.","solutions":["Use the built-in Intervention\\Image\\Colors\\Rgb\\Color (or convert via $color->toColorspace(new Rgb())) before exporting","In custom ColorInterface classes, keep Alpha::min() !== Alpha::max() and value() within [min, max]","Catch DriverException and inspect ->getPrevious() to confirm the range-division root cause"],"exampleFix":"// before\nclass BrandColor implements ColorInterface { /* alpha min()==max() == 0 */ }\n$gdInt = $processor->export(new BrandColor());\n\n// after\n$gdInt = $processor->export($color->toColorspace($processor->colorspace()));","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"function isExportableRgbColor(Intervention\\Image\\Interfaces\\ColorInterface $c): bool\n{\n    $colorspace = new Intervention\\Image\\Colors\\Rgb\\Colorspace();\n    $converted = $c->toColorspace($colorspace);\n\n    return $converted->channel(Intervention\\Image\\Colors\\Rgb\\Channels\\Alpha::class) instanceof Intervention\\Image\\Colors\\Rgb\\Channels\\Alpha;\n}","tryCatchPattern":"use Intervention\\Image\\Exceptions\\DriverException;\n\ntry {\n    $gdColor = $processor->export($color);\n} catch (DriverException $e) {\n    // custom color implementation broke the range contract; fall back to built-in color\n    $gdColor = $processor->export(new Intervention\\Image\\Colors\\Rgb\\Color(255, 0, 0));\n}","preventionTips":["Convert custom colors to RGB via toColorspace() before exporting to GD","Keep custom Alpha channels within their declared min/max range"],"tags":["gd","color","export","custom-color","defensive"],"backgroundTag":"color-conversion-failed","analyzedSha":"5598b9e39751c34afc5cdee84abef77f92c26f68","analyzedAt":"2026-08-23T02:17:31.068Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}