Intervention/image · error · ModifierException

Failed to apply Intervention\Image\Drivers\Imagick\Modifiers

Error message

Failed to apply Intervention\Image\Drivers\Imagick\Modifiers\ContainModifier, unable to set image background color

What it means

Thrown by ContainModifier::setFrameBackgroundTransparent() when setting the transparent background fails during $image->contain(). The step creates an ImagickPixel('transparent') and applies both setBackgroundColor() and setImageBackgroundColor(); either the combined false return or an ImagickException/ImagickPixelException triggers this ModifierException. It prepares the extended canvas areas that contain() later fills with your configured background.

Source

Thrown at src/Drivers/Imagick/Modifiers/ContainModifier.php:84

            throw new ModifierException(
                'Failed to apply ' . self::class . ', unable to resize image',
                previous: $e,
            );
        }
    }

    /**
     * Set the background and image background color of a frame to transparent.
     *
     * @throws ModifierException
     */
    private function setFrameBackgroundTransparent(Imagick $native): void
    {
        try {
            $transparent = new ImagickPixel('transparent');
            $result = $native->setBackgroundColor($transparent) && $native->setImageBackgroundColor($transparent);
            if ($result === false) {
                throw new ModifierException(
                    'Failed to apply ' . self::class . ', unable to set image background color',
                );
            }
        } catch (ImagickException | ImagickPixelException $e) {
            throw new ModifierException(
                'Failed to apply ' . self::class . ', unable to set image background color',
                previous: $e,
            );
        }
    }

    /**
     * Extend the canvas of a frame to the resize dimensions using the crop pivot as offset.
     *
     * @throws ModifierException
     */
    private function extendFrame(Imagick $native, SizeInterface $resize, SizeInterface $crop): void
    {

View on GitHub (pinned to 5598b9e397)

Solutions

1. Inspect $e->getPrevious() for the native ImagickException/ImagickPixelException message and address that root cause.
2. Sanity-check the environment: php -r '$p = new ImagickPixel("transparent"); var_dump($p->getColorAsString());' — failure means the extension install is broken; reinstall ext-imagick/ImageMagick.
3. Re-read the source image and run contain() as the first operation to rule out wand-state carryover.
4. If the environment stays broken, route contain-style workflows through the GD driver as a stopgap.

Example fix

// before
$image->contain(800, 600, background: 'f00'); // fails at transparent-background step

// after
try {
    $image->contain(800, 600, background: 'f00');
} catch (\Intervention\Image\Exceptions\ModifierException $e) {
    logger()->error('contain background step failed', ['native' => $e->getPrevious()?->getMessage() ?? 'n/a']);
    throw $e;
}

// environment probe for the background primitives this path depends on
$pixel = new \ImagickPixel('transparent');
$probe = new \Imagick();
$probe->newImage(2, 2, new \ImagickPixel('white'));
$ok = $probe->setBackgroundColor($pixel) && $probe->setImageBackgroundColor($pixel);
$probe->destroy();
if (!$ok) {
    throw new RuntimeException('imagick background ops unavailable');
}

use Intervention\Image\Exceptions\ModifierException;
try {
    $image->contain(800, 600);
} catch (ModifierException $e) {
    $native = $e->getPrevious()?->getMessage() ?? 'false return';
    logger()->error('contain background step failed', ['native' => $native]);
    // recover: re-read the image, or route to GD driver for this item
}

When it happens

Trigger: Calling $image->contain() on a frame where background color application fails: wand in error state, ImageMagick refusing background ops for the image's mode, or ImagickPixel construction failing (broken 'transparent' parsing in degraded builds).

Common situations: Contain workflows on hosts with damaged ImageMagick installs; processing images whose earlier pipeline steps left the wand inconsistent; rarely, extension builds where ImagickPixel color parsing is broken.

Related errors

• Failed to apply Intervention\Image\Drivers\Imagick\Modifiers
• Imagick driver can only process colors from instances of
• Failed to import color from
• Failed to apply Intervention\Image\Drivers\Imagick\Modifiers
• Failed to apply Intervention\Image\Drivers\Imagick\Modifiers

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