Intervention/image · error · InvalidArgumentException

Value for disposal method "$method" must be 0, 1, 2 or 3

Error message

Value for disposal method "$method" must be 0, 1, 2 or 3

What it means

GIF disposal methods are defined by the GIF89a specification as 0-3 (unspecified/none, do not dispose, restore to background, restore to previous). setDisposalMethod() enforces exactly that set; any other integer throws InvalidArgumentException.

Source

Thrown at src/Drivers/Gd/Frame.php:127

     *
     * @see FrameInterface::disposalMethod()
     */
    public function disposalMethod(): int
    {
        return $this->disposalMethod;
    }

    /**
     * {@inheritdoc}
     *
     * @see FrameInterface::setDisposalMethod()
     *
     * @throws InvalidArgumentException
     */
    public function setDisposalMethod(int $method): FrameInterface
    {
        if (!in_array($method, [0, 1, 2, 3])) {
            throw new InvalidArgumentException('Value for disposal method "$method" must be 0, 1, 2 or 3');
        }

        $this->disposalMethod = $method;

        return $this;
    }

    /**
     * {@inheritdoc}
     *
     * @see FrameInterface::setOffset()
     */
    public function setOffset(int $left, int $top): FrameInterface
    {
        $this->offsetLeft = $left;
        $this->offsetTop = $top;

        return $this;

View on GitHub (pinned to 5598b9e397)

Solutions

1. Map or clamp external values into 0-3 before setting
2. Use literals or named constants documented by the GIF89a spec
3. Validate with in_array($method, [0, 1, 2, 3], true) before the call

Example fix

// before
$frame->setDisposalMethod($externalValue); // may be 4 or more

// after
$method = in_array($externalValue, [0, 1, 2, 3], true) ? $externalValue : 0;
$frame->setDisposalMethod($method);

$method = in_array($externalValue, [0, 1, 2, 3], true) ? $externalValue : 0;
$frame->setDisposalMethod($method);

function isValidDisposalMethod(int $method): bool
{
    return in_array($method, [0, 1, 2, 3], true);
}

try {
    $frame->setDisposalMethod($value);
} catch (InvalidArgumentException $e) {
    $frame->setDisposalMethod(0); // clamp to 'unspecified'
}

When it happens

Trigger: $frame->setDisposalMethod(4) or values copied from external GIF tooling/parsers that emit out-of-range codes; uninitialized variables defaulting to -1 fed into the setter.

Common situations: Interoperating with custom GIF utilities that number disposal differently or emit experimental codes, copying raw metadata between libraries without mapping.

Related errors

• Failed to set image loop count
• Unable to parse RGB color from input "{input}"
• Invalid cmyk() color syntax "{input}"
• Unable to parse HSL color from input "{input}"
• Invalid hsl() color syntax "{input}"

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