{"record":{"id":"78180d709d2d6337","repo":"Intervention/image","slug":"failed-to-apply-intervention-image-drivers-gd-modi-78180d","errorCode":null,"errorMessage":"Failed to apply Intervention\\Image\\Drivers\\Gd\\Modifiers\\BrightnessModifier, unable to set image brightness","messagePattern":"Failed to apply Intervention\\\\Image\\\\Drivers\\\\Gd\\\\Modifiers\\\\BrightnessModifier, unable to set image brightness","errorType":"exception","errorClass":"ModifierException","httpStatus":null,"severity":"error","filePath":"src/Drivers/Gd/Modifiers/BrightnessModifier.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        foreach ($image as $frame) {\n            $result = imagefilter(\n                $frame->native(),\n                IMG_FILTER_BRIGHTNESS,\n                max(-255, min(255, intval($this->level * 2.55))),\n            );\n\n            if ($result === false) {\n                throw new ModifierException(\n                    'Failed to apply ' . self::class . ', unable to set image brightness',\n                );\n            }\n        }\n\n        return $image;\n    }\n}\n","sourceCodeStart":13,"sourceCodeEnd":40,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Drivers/Gd/Modifiers/BrightnessModifier.php#L13-L40","documentation":"BrightnessModifier passes IMG_FILTER_BRIGHTNESS with the level scaled to -255..255 for each frame; imagefilter() returning false is converted into ModifierException. With a valid GdImage native this is practically unreachable and signals an unusable native rather than a bad level value.","triggerScenarios":"->brightness(x) applied to a degenerate GdImage native; mocked/specialized driver setups that make imagefilter() fail (testApplyThrowsWhenSpecializedWithoutOverride).","commonSituations":"CI runs with substitute driver classes, images manipulated after a partial earlier failure leaving the core in a bad state.","solutions":["Catch ModifierException and degrade gracefully (skip the effect or the file)","Confirm the source image decodes cleanly before applying modifiers","Clone to a fresh truecolor native and retry once","Use the Imagick driver if a specific environment fails consistently"],"exampleFix":"// before\n$image->brightness(50);\n\n// after\ntry {\n    $image->brightness(50);\n} catch (ModifierException $e) {\n    logs()->warning('brightness 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->brightness(50);","typeGuard":"function isGdImage(mixed $value): bool\n{\n    return $value instanceof GdImage;\n}","tryCatchPattern":"try {\n    $image->brightness(50);\n} catch (ModifierException $e) {\n    // log, skip effect, or retry on a cloned truecolor copy\n}","preventionTips":["Abort pipelines on earlier soft failures instead of continuing","Wrap effect application per image in batch jobs","Prefer fresh clones over reusing mutated natives"],"tags":["brightness","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"}