{"record":{"id":"313d99151879690a","repo":"Intervention/image","slug":"failed-to-apply-colorize-effect","errorCode":null,"errorMessage":"Failed to apply colorize effect","messagePattern":"Failed to apply colorize effect","errorType":"exception","errorClass":"ModifierException","httpStatus":null,"severity":"error","filePath":"src/Drivers/Gd/Modifiers/ColorizeModifier.php","lineNumber":31,"sourceCode":"{\n    /**\n     * {@inheritdoc}\n     *\n     * @see ModifierInterface::apply()\n     *\n     * @throws ModifierException\n     */\n    public function apply(ImageInterface $image): ImageInterface\n    {\n        // normalize colorize levels\n        $red = (int) round($this->red * 2.55);\n        $green = (int) round($this->green * 2.55);\n        $blue = (int) round($this->blue * 2.55);\n\n        foreach ($image as $frame) {\n            $result = imagefilter($frame->native(), IMG_FILTER_COLORIZE, $red, $green, $blue);\n            if ($result === false) {\n                throw new ModifierException('Failed to apply colorize effect');\n            }\n        }\n\n        return $image;\n    }\n}\n","sourceCodeStart":13,"sourceCodeEnd":38,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Drivers/Gd/Modifiers/ColorizeModifier.php#L13-L38","documentation":"ColorizeModifier applies IMG_FILTER_COLORIZE with red/green/blue values scaled to -255..255 for each frame and converts a false imagefilter() result into ModifierException. Like the other GD filter wrappers, a false return indicates the native could not be processed, not that the colorize values were wrong (they are pre-clamped by the scaling).","triggerScenarios":"->colorize(r, g, b) on a degenerate or mocked GdImage native in test environments; images whose core became invalid after a prior partial failure.","commonSituations":"Automated test suites that force filter failure, batch pipelines continuing after an earlier soft failure corrupted frame natives.","solutions":["Catch ModifierException and skip or re-encode the affected image","Verify frame natives are valid GdImage instances before applying the modifier","Retry once on a freshly cloned truecolor copy","Switch to the Imagick driver for environments where GD misbehaves"],"exampleFix":"// before\n$image->colorize(50, 0, -50);\n\n// after\ntry {\n    $image->colorize(50, 0, -50);\n} catch (ModifierException $e) {\n    logs()->warning('colorize failed', ['file' => $fileId]);\n}","handlingStrategy":"try-catch","validationCode":"foreach ($image as $frame) {\n    if (!$frame->native() instanceof GdImage) {\n        throw new RuntimeException('Invalid frame native');\n    }\n}\n$image->colorize(50, 0, -50);","typeGuard":"function isGdImage(mixed $value): bool\n{\n    return $value instanceof GdImage;\n}","tryCatchPattern":"try {\n    $image->colorize(50, 0, -50);\n} catch (ModifierException $e) {\n    // log, skip effect, or retry on a cloned truecolor copy\n}","preventionTips":["Degrade per-image, not per-batch, on modifier failure","Verify pipeline preconditions (clean decode) before effects","Consider Imagick driver for environments with flaky GD builds"],"tags":["colorize","imagefilter","modifier","gd"],"backgroundTag":"image-filter-failed","analyzedSha":"5598b9e39751c34afc5cdee84abef77f92c26f68","analyzedAt":"2026-08-23T02:17:31.068Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}