{"record":{"id":"8140f141564abdfd","repo":"Intervention/image","slug":"failed-to-set-frame-disposal-method","errorCode":null,"errorMessage":"Failed to set frame disposal method","messagePattern":"Failed to set frame disposal method","errorType":"exception","errorClass":"DriverException","httpStatus":null,"severity":"error","filePath":"src/Drivers/Imagick/Frame.php","lineNumber":127,"sourceCode":"            return $this->native->getImageDelay() / 100;\n        } catch (ImagickException $e) {\n            throw new DriverException('Failed to get frame delay', previous: $e);\n        }\n    }\n\n    /**\n     * {@inheritdoc}\n     *\n     * @see DriverInterface::setDelay()\n     *\n     * @throws DriverException\n     */\n    public function setDelay(float $delay): FrameInterface\n    {\n        try {\n            $this->native->setImageDelay(intval(round($delay * 100)));\n        } catch (ImagickException $e) {\n            throw new DriverException('Failed to set frame disposal method', previous: $e);\n        }\n\n        return $this;\n    }\n\n    /**\n     * {@inheritdoc}\n     *\n     * @see DriverInterface::disposalMethod()\n     *\n     * @throws DriverException\n     */\n    public function disposalMethod(): int\n    {\n        try {\n            return $this->native->getImageDispose();\n        } catch (ImagickException $e) {\n            throw new DriverException('Failed to get frame disposal method', previous: $e);","sourceCodeStart":109,"sourceCodeEnd":145,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Drivers/Imagick/Frame.php#L109-L145","documentation":"Frame::setDelay() stores the animation delay as setImageDelay(intval(round($delay * 100))) (src/Drivers/Imagick/Frame.php:125) — input is seconds, ImageMagick keeps ticks of 1/100s. The message text 'Failed to set frame disposal method' is a copy/paste mistake in the library (the same message exists on setDisposalMethod at line 166): the failure actually concerns the delay. The wrapped ImagickException means an invalid delay value or an unusable native object.","triggerScenarios":"Setting a negative delay (setDelay(-0.5) maps to setImageDelay(-50)) or a value that overflows the tick range; calling setDelay() on a frame whose native Imagick was cleared/destroyed.","commonSituations":"Computing delays from user input or frame-diff math without clamping; loops that normalize frame speeds and accidentally produce zero/negative values; reusing frames after teardown of the core.","solutions":["Clamp the delay before setting: $frame->setDelay(max(0.01, $delay))","Pass the delay in seconds (0.04 for 25 fps), not in ticks or milliseconds","Confirm via stack trace that setDelay() threw — the message misleadingly names the disposal method","Do not reuse frames whose native was cleared; re-read the source image"],"exampleFix":"// before\n$frame->setDelay($newDelay); // may be negative or huge\n\n// after\n$frame->setDelay(max(0.01, min(655.35, $newDelay)));","handlingStrategy":"validation","validationCode":"// setDelay() takes SECONDS; clamp to a sane positive range before calling\n$delay = max(0.01, min(655.35, (float) $delay));\nif (!is_finite($delay)) {\n    throw new InvalidArgumentException('Delay must be a finite number of seconds');\n}\n$frame->setDelay($delay);","typeGuard":"function isValidFrameDelay(mixed $delay): bool\n{\n    return is_float($delay) || is_int($delay)\n        ? $delay >= 0 && $delay <= 655.35\n        : false;\n}","tryCatchPattern":"use Intervention\\Image\\Exceptions\\DriverException;\n\ntry {\n    $frame->setDelay($normalized);\n} catch (DriverException $e) {\n    // message says 'disposal method' but this path is setDelay(); check the trace\n    if (str_ends_with($e->getTrace()[0]['function'] ?? '', 'setDelay')) {\n        $frame->setDelay(0.1); // safe default\n    } else {\n        throw $e;\n    }\n}","preventionTips":["Remember the unit contract: seconds in, ticks (1/100s) stored","Clamp computed delays (from user input or frame diffs) to [0.01, 655.35]","Do not call setDelay() on frames whose native was cleared; re-read the source"],"tags":["imagick","frame","animation","delay","invalid-value"],"backgroundTag":"invalid-animation-delay","analyzedSha":"5598b9e39751c34afc5cdee84abef77f92c26f68","analyzedAt":"2026-08-23T02:17:31.068Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}