Intervention/image · error · StateException

The stroke color must be fully opaque

Error message

The stroke color must be fully opaque

What it means

TextModifier::strokeColor() decodes the font's stroke color for the text outline effect. Because the outline is drawn underneath the actual text (TextModifier.php:30-33), a fully transparent stroke color would either be invisible or interfere with the layering, so any transparent decoded stroke color throws StateException. Note the default stroke color is opaque white ('ffffff' in Font.php:28), so this only fires when a transparent stroke color is set explicitly.

Source

Thrown at src/Modifiers/TextModifier.php:60

            throw new StateException(
                'The text color must be fully opaque when using the stroke effect',
            );
        }

        return $color;
    }

    /**
     * Decode outline stroke color.
     *
     * @throws StateException
     */
    protected function strokeColor(): ColorInterface
    {
        $color = $this->driver()->decodeColor($this->font->strokeColor());

        if ($color->isTransparent()) {
            throw new StateException(
                'The stroke color must be fully opaque',
            );
        }

        return $color;
    }

    /**
     * Return array of offset points to draw text stroke effect below the actual text.
     *
     * @return array<PointInterface>
     */
    protected function strokeOffsets(FontInterface $font): array
    {
        $offsets = [];

        if ($font->strokeWidth() <= 0) {
            return $offsets;

View on GitHub (pinned to 5598b9e397)

Solutions

1. Use a fully opaque stroke color such as '000000' or 'ffffff'
2. To disable the outline, set $font->strokeWidth(0) instead of a transparent stroke color
3. Validate configured stroke colors for full opacity before rendering text

Example fix

// before
$font->strokeColor('transparent');

// after
$font->strokeWidth(0); // outline disabled properly

use Intervention\Image\Colors\Rgb\Color;

// Before rendering stroked text, ensure the stroke color is opaque
$stroke = $font->strokeColor();
$isTransparent = $stroke instanceof Color ? $stroke->isTransparent() : $stroke === 'transparent';

if ($isTransparent) {
    $font->strokeWidth(0); // disable outline instead of a transparent stroke
}

$image->text('caption', 10, 10, $font);

function hasOpaqueStrokeColor($font): bool
{
    $stroke = $font->strokeColor();

    return !($stroke === 'transparent'
        || (str_starts_with((string) $stroke, 'rgba') && str_ends_with((string) $stroke, ', 0)')));
}

// exact check requires decoding through the driver; avoid transparent stroke colors in stroked configs

use Intervention\Image\Exceptions\StateException;

try {
    $image->text('Watermark', 10, 10, $font);
} catch (StateException $e) {
    // message: 'The stroke color must be fully opaque'
    $font->strokeColor('000000');
    $image->text('Watermark', 10, 10, $font);
}

When it happens

Trigger: Setting $font->strokeColor('transparent') or $font->strokeColor('rgba(255, 255, 255, 0)') on a font used with $image->text(); the exception is raised when the driver renders the stroke, not when the color is set.

Common situations: Theme-driven watermark configs where 'none' is encoded as 'transparent'; attempting to disable the outline by making it transparent instead of setting strokeWidth to 0; copying color values with an alpha channel of 0 from a design tool.

Related errors

• The text color must be fully opaque when using the stroke ef
• The text color must be fully opaque when using the stroke ef
• The stroke color must be fully opaque
• Unable to parse RGB color from input "{input}"
• No font file specified

AI-assisted analysis of Intervention/image@5598b9e397 (2026-08-23). Data as JSON: /api/errors/ddf17038354f3f9b. Report an issue: GitHub.