Intervention/image · error · DriverException

Failed to set frame offset

Error message

Failed to set frame offset

What it means

Thrown by Frame::setOffset() when Imagick::setImagePage() fails with an ImagickException. setOffset() rewrites the frame's page geometry using the current image width/height plus your left/top coordinates, which is how GIF frame positioning works. The raw native failure is chained as previous.

Source

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

    /**
     * {@inheritdoc}
     *
     * @see DriverInterface::setOffset()
     *
     * @throws DriverException
     */
    public function setOffset(int $left, int $top): FrameInterface
    {
        try {
            $this->native->setImagePage(
                $this->native->getImageWidth(),
                $this->native->getImageHeight(),
                $left,
                $top,
            );
        } catch (ImagickException $e) {
            throw new DriverException('Failed to set frame offset', previous: $e);
        }

        return $this;
    }

    /**
     * {@inheritdoc}
     *
     * @see DriverInterface::offsetLeft()
     *
     * @throws DriverException
     */
    public function offsetLeft(): int
    {
        try {
            return $this->native->getImagePage()['x'];
        } catch (ImagickException $e) {
            throw new DriverException('Failed to get frame offset', previous: $e);

View on GitHub (pinned to 5598b9e397)

Solutions

1. Check $e->getPrevious() for the concrete ImagickException and resolve the root cause (corrupt frame, destroyed handle).
2. Confirm frame integrity first: if ($frame->size()->width() <= 0) skip or rebuild the frame.
3. Clamp offsets to sane bounds derived from the canvas size before calling setOffset(); validate externally supplied coordinates.

Example fix

// before
$frame->setOffsetLeft((int) $request->input('left')); // arbitrary user value

// after
$left = max(0, min((int) $request->input('left'), $canvasWidth - $frame->size()->width()));
$frame->setOffsetLeft($left);

$left = max(0, min((int) $left, $canvasWidth - 1));
$top = max(0, min((int) $top, $canvasHeight - 1));
if ($frame->size()->width() > 0) {
    $frame->setOffset($left, $top);
}

use Intervention\Image\Exceptions\DriverException;
try {
    $frame->setOffset($left, $top);
} catch (DriverException $e) {
    // inspect $e->getPrevious(); usually a stale/corrupt wand — rebuild frame
}

When it happens

Trigger: Calling setOffset(), setOffsetLeft(), or setOffsetTop() (the latter two delegate to setOffset) with coordinates on a frame whose native wand is invalid or whose dimensions cannot be read. Extremely large/negative integers that overflow ImageMagick's geometry parsing can also trigger it, as can a destroyed or zero-frame Imagick object.

Common situations: Composing animated GIFs from offset tiles where one tile's source failed to decode; passing unvalidated user offsets from an editor UI; reusing frame objects after the parent image was garbage-collected in long pipelines.

Related errors

• Failed to get frame offset
• Failed to get frame disposal method
• Failed to get image loop count
• Failed to set image loop count
• Failed to coalesce image

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