{"record":{"id":"3f472544b62c1ec7","repo":"Intervention/image","slug":"failed-to-get-frame-offset","errorCode":null,"errorMessage":"Failed to get frame offset","messagePattern":"Failed to get frame offset","errorType":"exception","errorClass":"DriverException","httpStatus":null,"severity":"error","filePath":"src/Drivers/Imagick/Frame.php","lineNumber":207,"sourceCode":"            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);\n        }\n    }\n\n    /**\n     * {@inheritdoc}\n     *\n     * @see DriverInterface::setOffsetLeft()\n     *\n     * @throws RuntimeException\n     */\n    public function setOffsetLeft(int $offset): FrameInterface\n    {\n        return $this->setOffset($offset, $this->offsetTop());\n    }\n\n    /**\n     * {@inheritdoc}\n     *","sourceCodeStart":189,"sourceCodeEnd":225,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Drivers/Imagick/Frame.php#L189-L225","documentation":"Thrown by Frame::offsetLeft() when Imagick::getImagePage() raises an ImagickException while reading the page geometry's x coordinate. The page x/y values are the frame's offset within the animation canvas, used when compositing or splitting animated images. The native exception is preserved as previous.","triggerScenarios":"Calling offsetLeft() (directly, or via setOffsetTop() which reads the current left offset) on a frame whose Imagick wand is in an error state, was destroyed, or belongs to an image whose decode produced no usable frame. Rare builds of ImageMagick can also fail page queries on malformed GIF headers.","commonSituations":"GIF split/explode workflows reading every frame's offset; calling setOffsetTop() on the first frame of a freshly decoded but truncated upload; workers that previously mutated the native handle directly and left it inconsistent.","solutions":["Inspect $e->getPrevious() for the real Imagick error and fix the underlying wand state or input file.","Validate the image decoded cleanly before iterating frames (e.g. check width()/height() succeed).","Where only the composite geometry matters, prefer the higher-level animation APIs rather than reading each frame's raw page offset."],"exampleFix":"// before\n$left = $frame->offsetLeft(); // may throw on corrupt frame\n\n// after\nuse Intervention\\Image\\Exceptions\\DriverException;\ntry {\n    $left = $frame->offsetLeft();\n} catch (DriverException $e) {\n    $left = 0; // treat unreadable metadata as no offset\n}","handlingStrategy":"try-catch","validationCode":"if ($frame->size()->width() < 1) {\n    throw new RuntimeException('frame not readable; offsets unavailable');\n}","typeGuard":"function safeOffsetLeft(\\Intervention\\Image\\Drivers\\Imagick\\Frame $frame, int $default = 0): int\n{\n    try {\n        return $frame->offsetLeft();\n    } catch (\\Intervention\\Image\\Exceptions\\DriverException) {\n        return $default;\n    }\n}","tryCatchPattern":"use Intervention\\Image\\Exceptions\\DriverException;\ntry {\n    $x = $frame->offsetLeft();\n} catch (DriverException $e) {\n    $x = 0; // offsets are optional metadata for most compositing flows\n}","preventionTips":["Treat page offsets as optional metadata with a documented default rather than load-bearing data.","Fully re-encode untrusted animated uploads once before frame-level analysis."],"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"}