Intervention/image · error · InvalidArgumentException

Position must be either integer or a percent value as string

Error message

Position must be either integer or a percent value as string

What it means

Error "Position must be either integer or a percent value as string" thrown in Intervention/image.

Source

Thrown at src/Modifiers/RemoveAnimationModifier.php:49

    /**
     * Return the position of the selected frame as integer.
     *
     * @throws InvalidArgumentException
     */
    protected function normalizePosition(ImageInterface $image): int
    {
        if (is_int($this->position)) {
            return $this->position;
        }

        if (is_numeric($this->position)) {
            return (int) $this->position;
        }

        // calculate position from percentage value
        if (preg_match("/^(?P<percent>[0-9]{1,3})%$/", $this->position, $matches) !== 1) {
            throw new InvalidArgumentException(
                'Position must be either integer or a percent value as string',
            );
        }

        $total = count($image);
        $position = intval(round($total / 100 * intval($matches['percent'])));

        return $position === $total ? $position - 1 : $position;
    }
}

View on GitHub (pinned to 5598b9e397)

Solutions

1. Pass the position as an integer frame index (e.g. 0) or a percent string (e.g. "25%")
2. Cast float positions to int or convert them to a percent string
3. Reject other types (arrays, null) at the call site

When it happens

Trigger: Thrown at src/Modifiers/RemoveAnimationModifier.php:49 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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