{"record":{"id":"5905b413aef7cc2d","repo":"Intervention/image","slug":"failed-to-set-frame-offset","errorCode":null,"errorMessage":"Failed to set frame offset","messagePattern":"Failed to set frame offset","errorType":"exception","errorClass":"DriverException","httpStatus":null,"severity":"error","filePath":"src/Drivers/Imagick/Frame.php","lineNumber":189,"sourceCode":"\n    /**\n     * {@inheritdoc}\n     *\n     * @see DriverInterface::setOffset()\n     *\n     * @throws DriverException\n     */\n    public function setOffset(int $left, int $top): FrameInterface\n    {\n        try {\n            $this->native->setImagePage(\n                $this->native->getImageWidth(),\n                $this->native->getImageHeight(),\n                $left,\n                $top,\n            );\n        } catch (ImagickException $e) {\n            throw new DriverException('Failed to set frame offset', previous: $e);\n        }\n\n        return $this;\n    }\n\n    /**\n     * {@inheritdoc}\n     *\n     * @see DriverInterface::offsetLeft()\n     *\n     * @throws DriverException\n     */\n    public function offsetLeft(): int\n    {\n        try {\n            return $this->native->getImagePage()['x'];\n        } catch (ImagickException $e) {\n            throw new DriverException('Failed to get frame offset', previous: $e);","sourceCodeStart":171,"sourceCodeEnd":207,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Drivers/Imagick/Frame.php#L171-L207","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check $e->getPrevious() for the concrete ImagickException and resolve the root cause (corrupt frame, destroyed handle).","Confirm frame integrity first: if ($frame->size()->width() <= 0) skip or rebuild the frame.","Clamp offsets to sane bounds derived from the canvas size before calling setOffset(); validate externally supplied coordinates."],"exampleFix":"// before\n$frame->setOffsetLeft((int) $request->input('left')); // arbitrary user value\n\n// after\n$left = max(0, min((int) $request->input('left'), $canvasWidth - $frame->size()->width()));\n$frame->setOffsetLeft($left);","handlingStrategy":"validation","validationCode":"$left = max(0, min((int) $left, $canvasWidth - 1));\n$top = max(0, min((int) $top, $canvasHeight - 1));\nif ($frame->size()->width() > 0) {\n    $frame->setOffset($left, $top);\n}","typeGuard":null,"tryCatchPattern":"use Intervention\\Image\\Exceptions\\DriverException;\ntry {\n    $frame->setOffset($left, $top);\n} catch (DriverException $e) {\n    // inspect $e->getPrevious(); usually a stale/corrupt wand — rebuild frame\n}","preventionTips":["Clamp user-supplied offsets to the canvas bounds before calling setOffset/setOffsetLeft/setOffsetTop.","Verify frame dimensions read successfully before positioning."],"tags":["imagick","animation","gif","offset","driver-exception"],"backgroundTag":"imagick-driver-exception","analyzedSha":"5598b9e39751c34afc5cdee84abef77f92c26f68","analyzedAt":"2026-08-23T02:17:31.068Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}