Intervention/image · error · InvalidArgumentException

Offset is not in the range of frames

Error message

Offset is not in the range of frames

What it means

sliceAnimation($offset, $length) keeps only the frames starting at the 0-based offset. The GD implementation first checks that the offset is smaller than the number of frames in the core and throws InvalidArgumentException otherwise. A decoded still image counts as one frame, so only offset 0 is valid there; a five-frame GIF accepts offsets 0 through 4.

Source

Thrown at src/Drivers/Gd/Modifiers/SliceAnimationModifier.php:24

use Intervention\Image\Exceptions\InvalidArgumentException;
use Intervention\Image\Interfaces\ImageInterface;
use Intervention\Image\Interfaces\SpecializedInterface;
use Intervention\Image\Modifiers\SliceAnimationModifier as GenericSliceAnimationModifier;

class SliceAnimationModifier extends GenericSliceAnimationModifier implements SpecializedInterface
{
    /**
     * {@inheritdoc}
     *
     * @see ModifierInterface::apply()
     *
     * @throws InvalidArgumentException
     */
    public function apply(ImageInterface $image): ImageInterface
    {
        if ($this->offset >= $image->count()) {
            throw new InvalidArgumentException('Offset is not in the range of frames');
        }

        $image->core()->slice($this->offset, $this->length);

        return $image;
    }
}

View on GitHub (pinned to 5598b9e397)

Solutions

1. Use a 0-based offset strictly smaller than $image->count()
2. For the last frame: $image->sliceAnimation($image->count() - 1, 1)
3. Clamp dynamic offsets: $offset = min($offset, $image->count() - 1)
4. Guard stills with $image->isAnimated() before slicing

Example fix

// before: off-by-one on a 5-frame gif
$image->sliceAnimation(5);

// after: keep only the last frame
$image->sliceAnimation($image->count() - 1, 1);

$offset = 5;

if ($offset >= $image->count()) {
    throw new InvalidArgumentException(sprintf(
        'Offset %d out of range for %d frames',
        $offset,
        $image->count()
    ));
}

$image->sliceAnimation($offset, $length);

function isValidSliceOffset(int $offset, ImageInterface $image): bool
{
    return $offset >= 0 && $offset < $image->count();
}

use Intervention\Image\Exceptions\InvalidArgumentException;

try {
    $image->sliceAnimation($offset, $length);
} catch (InvalidArgumentException $e) {
    // clamp to the last valid frame and retry
    $image->sliceAnimation($image->count() - 1, $length);
}

When it happens

Trigger: $image->sliceAnimation(5) on a 5-frame GIF (valid maximum is 4); sliceAnimation(1) or higher on a non-animated single-frame image; an offset computed as count($frames) to grab the last frame (off-by-one); applying the call to images that may or may not be animated.

Common situations: Frame selectors driven by user input; 1-based indexing assumptions; 'take the last frame' logic; batch jobs processing mixed still/animated content.

Related errors

• Frame #${position} could not be found in the image
• Normalized color value must be in range 0 to 1
• The specified position ({x}, {y}) is not within the image ar
• Invalid image size
• GD driver can only decode colors in integer or array format

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