{"record":{"id":"2b48a12d018ecf4a","repo":"Intervention/image","slug":"the-stroke-color-must-be-fully-opaque","errorCode":null,"errorMessage":"The stroke color must be fully opaque","messagePattern":"The stroke color must be fully opaque","errorType":"exception","errorClass":"StateException","httpStatus":null,"severity":"error","filePath":"src/Drivers/Gd/Modifiers/TextModifier.php","lineNumber":143,"sourceCode":"            ->colorProcessor($image)\n            ->export(parent::textColor());\n    }\n\n    /**\n     * Decode color for stroke (outline) effect in GD compatible format\n     *\n     * @throws StateException\n     */\n    protected function gdStrokeColor(ImageInterface $image): int\n    {\n        if (!$this->font->hasStrokeEffect()) {\n            return 0;\n        }\n\n        $color = parent::strokeColor();\n\n        if ($color->isTransparent()) {\n            throw new StateException('The stroke color must be fully opaque');\n        }\n\n        return $this\n            ->driver()\n            ->colorProcessor($image)\n            ->export($color);\n    }\n\n    /**\n     * Return GD's internal font size\n     */\n    private function gdFont(): int\n    {\n        if (!in_array($this->font->size(), range(1, 5))) {\n            return 1;\n        }\n\n        return (int) $this->font->size();","sourceCodeStart":125,"sourceCodeEnd":161,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Drivers/Gd/Modifiers/TextModifier.php#L125-L161","documentation":"The GD driver fakes a text stroke by drawing the text repeatedly at pixel offsets in the stroke color beneath the real text, so a semi-transparent stroke would bleed through the glyphs and break the effect. gdStrokeColor() therefore rejects any stroke color whose alpha is below fully opaque (isTransparent() is true for any alpha < 1) with StateException, but only when a stroke effect is active (strokeWidth > 0). Defaults are opaque ('ffffff' stroke, '000000' text), so the error requires an explicitly transparent stroke color; the Imagick driver renders alpha strokes natively and does not throw.","triggerScenarios":"$image->text(...) with fn($font) => $font->stroke('rgba(255,255,255,0.5)', 2); a stroke color of 'transparent' or any ColorInterface with alpha < 1 while strokeWidth > 0; typography code written against the Imagick driver then run under GD.","commonSituations":"Design systems specifying rgba() outline colors; theme color tokens with alpha reused for captions and watermarks; driver-agnostic code tested only with Imagick.","solutions":["Use a fully opaque stroke color: '#ffffff', 'rgb(255, 255, 255)' or an Rgb\\Color with alpha 1","Drop the stroke effect (strokeWidth 0) when transparency is the goal","Pre-blend the intended color against the known background to get an opaque equivalent","Switch to the Imagick driver if alpha strokes are a hard requirement"],"exampleFix":"// before\n$image->text('Draft', 40, 40, fn($font) => $font\n    ->file('arial.ttf')\n    ->stroke('rgba(255,255,255,0.5)', 2));\n\n// after: fully opaque stroke color\n$image->text('Draft', 40, 40, fn($font) => $font\n    ->file('arial.ttf')\n    ->stroke('#ffffff', 2));","handlingStrategy":"validation","validationCode":"use Intervention\\Image\\Colors\\Rgb\\Color as RgbColor;\n\n$stroke = 'rgba(255,255,255,0.5)';\n\nif ($font->strokeWidth() > 0) {\n    $color = RgbColor::parse($stroke); // hex / rgb() / rgba() / named strings\n\n    if ($color->isTransparent()) {\n        throw new RuntimeException(\n            'GD requires a fully opaque stroke color; use e.g. #ffffff instead'\n        );\n    }\n}\n\n$image->text('Draft', 40, 40, $font);","typeGuard":null,"tryCatchPattern":"use Intervention\\Image\\Exceptions\\StateException;\n\ntry {\n    $image->text('Draft', 40, 40, $font);\n} catch (StateException $e) {\n    // retry with a fully opaque stroke color\n    $font->setStrokeColor('#ffffff');\n    $image->text('Draft', 40, 40, $font);\n}","preventionTips":["Keep stroke colors opaque in GD pipelines; alpha belongs to fills, not outlines.","If alpha strokes are required, switch the pipeline to the Imagick driver.","Test text effects under every driver you ship.","Pre-blend rgba outline colors against the known background to get opaque equivalents."],"tags":["gd","text","typography","stroke","alpha","transparency"],"backgroundTag":"gd-alpha-unsupported","analyzedSha":"5598b9e39751c34afc5cdee84abef77f92c26f68","analyzedAt":"2026-08-23T02:17:31.068Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}