{"record":{"id":"36211892091463ba","repo":"Intervention/image","slug":"the-text-color-must-be-fully-opaque-when-using-the","errorCode":null,"errorMessage":"The text color must be fully opaque when using the stroke effect","messagePattern":"The text color must be fully opaque when using the stroke effect","errorType":"exception","errorClass":"StateException","httpStatus":null,"severity":"error","filePath":"src/Drivers/Imagick/Modifiers/TextModifier.php","lineNumber":70,"sourceCode":"            }\n        }\n\n        return $image;\n    }\n\n    /**\n     * Create an ImagickDraw object to draw text on the image\n     *\n     * @throws StateException\n     * @throws DriverException\n     * @throws RuntimeException\n     */\n    private function imagickDrawText(ImageInterface $image, FontInterface $font): ImagickDraw\n    {\n        $color = $this->driver()->decodeColor($font->color());\n\n        if ($font->hasStrokeEffect() && $color->isTransparent()) {\n            throw new StateException(\n                'The text color must be fully opaque when using the stroke effect',\n            );\n        }\n\n        $color = $this->driver()->colorProcessor($image)->export($color);\n\n        return $this->processor()->toImagickDraw($font, $color);\n    }\n\n    /**\n     * Create a ImagickDraw object to draw the outline stroke effect on the Image\n     *\n     * @throws StateException\n     * @throws DriverException\n     * @throws RuntimeException\n     */\n    private function imagickDrawStroke(ImageInterface $image, FontInterface $font): ?ImagickDraw\n    {","sourceCodeStart":52,"sourceCodeEnd":88,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Drivers/Imagick/Modifiers/TextModifier.php#L52-L88","documentation":"StateException from the Imagick text modifier: when the font has a stroke effect enabled, the text fill color must be fully opaque. The check decodes the configured color and rejects any transparent value before it is exported to an Imagick pixel value, because a transparent fill under a stroke outline produces broken output in ImageMagick's renderer.","triggerScenarios":"$image->text('label', $x, $y, fn ($font) => $font->color('rgba(255,255,255,0)')->stroke('000', 1)) - any text color with alpha below 1 (including 'transparent' or 8-digit hex with 00 alpha) combined with a stroke effect.","commonSituations":"Porting watermark/label styles from CSS where semi-transparent text plus an outline is common; reusing a palette color that carries alpha for text; config presets that always set a stroke width even when the color is meant to be see-through.","solutions":["Use a fully opaque text color (e.g. '#ffffff' or 'rgba(255,255,255,1)') when a stroke effect is set","Drop the stroke effect if transparent text is intentional","Draw the text on a separate layer with the desired opacity and blend the layer instead of using alpha on the fill"],"exampleFix":"// before\n$image->text('watermark', 10, 10, fn ($font) => $font\n    ->color('rgba(255,255,255,0.4)')\n    ->stroke('000000', 1)\n);\n\n// after\n$image->text('watermark', 10, 10, fn ($font) => $font\n    ->color('#ffffff')\n    ->stroke('000000', 1)\n);","handlingStrategy":"validation","validationCode":"// only pair a stroke effect with fully opaque hex fill colors\nif ($strokeWidth > 0 && !preg_match('/^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i', $textColor)) {\n    throw new InvalidArgumentException(\n        'Text color must be fully opaque (e.g. #ffffff) when using a stroke effect'\n    );\n}\n$image->text($caption, $x, $y, fn ($font) => $font->color($textColor)->stroke($strokeColor, $strokeWidth));","typeGuard":"function isOpaqueHexColor(string $color): bool\n{\n    return (bool) preg_match('/^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i', $color);\n}","tryCatchPattern":"use Intervention\\Image\\Exceptions\\StateException;\n\ntry {\n    $image->text($caption, $x, $y, $fontCallback);\n} catch (StateException $e) {\n    // configuration bug - fix the color config, do not retry\n    throw new InvalidArgumentException('Invalid text config: ' . $e->getMessage(), 0, $e);\n}","preventionTips":["Never combine rgba()/8-digit-hex alpha with ->stroke() in font configs","Centralize text style presets and test each with and without stroke","Treat this error as a config bug: fail loudly in development instead of catching it in production"],"tags":["imagick","text","font","stroke","color","state"],"backgroundTag":"invalid-color-value","analyzedSha":"5598b9e39751c34afc5cdee84abef77f92c26f68","analyzedAt":"2026-08-23T02:17:31.068Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}