{"record":{"id":"e40a7f632763e5fe","repo":"Intervention/image","slug":"failed-to-apply-intervention-image-drivers-imagick-e40a7f","errorCode":null,"errorMessage":"Failed to apply Intervention\\Image\\Drivers\\Imagick\\Modifiers\\ContainModifier, unable to set image background color","messagePattern":"Failed to apply Intervention\\\\Image\\\\Drivers\\\\Imagick\\\\Modifiers\\\\ContainModifier, unable to set image background color","errorType":"exception","errorClass":"ModifierException","httpStatus":null,"severity":"error","filePath":"src/Drivers/Imagick/Modifiers/ContainModifier.php","lineNumber":84,"sourceCode":"            throw new ModifierException(\n                'Failed to apply ' . self::class . ', unable to resize image',\n                previous: $e,\n            );\n        }\n    }\n\n    /**\n     * Set the background and image background color of a frame to transparent.\n     *\n     * @throws ModifierException\n     */\n    private function setFrameBackgroundTransparent(Imagick $native): void\n    {\n        try {\n            $transparent = new ImagickPixel('transparent');\n            $result = $native->setBackgroundColor($transparent) && $native->setImageBackgroundColor($transparent);\n            if ($result === false) {\n                throw new ModifierException(\n                    'Failed to apply ' . self::class . ', unable to set image background color',\n                );\n            }\n        } catch (ImagickException | ImagickPixelException $e) {\n            throw new ModifierException(\n                'Failed to apply ' . self::class . ', unable to set image background color',\n                previous: $e,\n            );\n        }\n    }\n\n    /**\n     * Extend the canvas of a frame to the resize dimensions using the crop pivot as offset.\n     *\n     * @throws ModifierException\n     */\n    private function extendFrame(Imagick $native, SizeInterface $resize, SizeInterface $crop): void\n    {","sourceCodeStart":66,"sourceCodeEnd":102,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Drivers/Imagick/Modifiers/ContainModifier.php#L66-L102","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Inspect $e->getPrevious() for the native ImagickException/ImagickPixelException message and address that root cause.","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.","Re-read the source image and run contain() as the first operation to rule out wand-state carryover.","If the environment stays broken, route contain-style workflows through the GD driver as a stopgap."],"exampleFix":"// before\n$image->contain(800, 600, background: 'f00'); // fails at transparent-background step\n\n// after\ntry {\n    $image->contain(800, 600, background: 'f00');\n} catch (\\Intervention\\Image\\Exceptions\\ModifierException $e) {\n    logger()->error('contain background step failed', ['native' => $e->getPrevious()?->getMessage() ?? 'n/a']);\n    throw $e;\n}","handlingStrategy":"try-catch","validationCode":"// environment probe for the background primitives this path depends on\n$pixel = new \\ImagickPixel('transparent');\n$probe = new \\Imagick();\n$probe->newImage(2, 2, new \\ImagickPixel('white'));\n$ok = $probe->setBackgroundColor($pixel) && $probe->setImageBackgroundColor($pixel);\n$probe->destroy();\nif (!$ok) {\n    throw new RuntimeException('imagick background ops unavailable');\n}","typeGuard":null,"tryCatchPattern":"use Intervention\\Image\\Exceptions\\ModifierException;\ntry {\n    $image->contain(800, 600);\n} catch (ModifierException $e) {\n    $native = $e->getPrevious()?->getMessage() ?? 'false return';\n    logger()->error('contain background step failed', ['native' => $native]);\n    // recover: re-read the image, or route to GD driver for this item\n}","preventionTips":["Smoke-test ImagickPixel('transparent') parsing and background ops when provisioning hosts.","Run contain() early in the pipeline, before native-level edits can destabilize the wand."],"tags":["imagick","contain","background","imagickpixel","modifier-exception"],"backgroundTag":"image-modifier-failed","analyzedSha":"5598b9e39751c34afc5cdee84abef77f92c26f68","analyzedAt":"2026-08-23T02:17:31.068Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}