Intervention/image · error · InvalidArgumentException

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

Error message

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

What it means

Thrown by Frame::setDisposalMethod() when the integer passed is not one of 0, 1, 2 or 3. These values map to ImageMagick disposal constants: 0 = undefined, 1 = none, 2 = background, 3 = previous. It is a pure input-validation error (InvalidArgumentException) raised before any native call is made, so nothing has been modified when it fires.

Source

Thrown at src/Drivers/Imagick/Frame.php:160

        try {
            return $this->native->getImageDispose();
        } catch (ImagickException $e) {
            throw new DriverException('Failed to get frame disposal method', previous: $e);
        }
    }

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

        try {
            $this->native->setImageDispose($method);
        } catch (ImagickException $e) {
            throw new DriverException('Failed to set frame disposal method', previous: $e);
        }

        return $this;
    }

    /**
     * {@inheritdoc}
     *
     * @see DriverInterface::setOffset()
     *
     * @throws DriverException
     */

View on GitHub (pinned to 5598b9e397)

Solutions

Map your value to the supported set: only 0 (undefined), 1 (none), 2 (background), 3 (previous) are accepted; clamp or reject anything else before calling.
If you need richer disposal modes, drop to the native handle: $frame->native()->setImageDispose(Imagick::DISPOSE_BLOCK) accepts the full constant set.
Validate persisted/config-sourced disposal values with an allowlist at the boundary (config load, API deserialization) rather than at the image call site.

Example fix

// before
$frame->setDisposalMethod(Imagick::DISPOSE_BLOCK); // 7 -> InvalidArgumentException

// after
$frame->setDisposalMethod(2); // 0=undefined, 1=none, 2=background, 3=previous

Defensive patterns

Strategy: validation

Validate before calling

$method = (int) $config['disposal'] ?? 0;
if (!in_array($method, [0, 1, 2, 3], true)) {
    throw new \InvalidArgumentException('disposal method must be 0, 1, 2 or 3');
}
$frame->setDisposalMethod($method);

Type guard

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

Try / catch

use Intervention\Image\Exceptions\InvalidArgumentException;
try {
    $frame->setDisposalMethod($method);
} catch (InvalidArgumentException $e) {
    // coerce to the supported set and retry once
    $frame->setDisposalMethod(max(0, min($method, 3)));
}

Prevention

Validate disposal values at the config/API boundary with an allowlist, not at the image call site.
Map names to values once: 'undefined'=>0, 'none'=>1, 'background'=>2, 'previous'=>3.
Never pass raw Imagick disposal constants (4+) to the driver-level API; use $frame->native()->setImageDispose() if you truly need them.

When it happens

Trigger: Calling setDisposalMethod() (directly or via animation helpers) with a value outside the whitelist, e.g. 4+ taken from newer ImageMagick disposal constants (DISPOSE_BLOCK etc.) or from external metadata/API payloads. Passing user input cast from a string like 'background' via intval() (which yields 0 only by luck) or an unvalidated query parameter.

Common situations: Porting code that used raw Imagick constants such as Imagick::DISPOSE_BLOCK (value 7) or Imagick::DISPOSE_BREAK (4); feeding disposal values from an animation JSON config or database column without validation; off-by-one or enum-to-int mapping mistakes between GD and Imagick drivers.

Related errors

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