{"record":{"id":"aa913abfc341d31b","repo":"Intervention/image","slug":"frame-position-could-not-be-found-in-the-image","errorCode":null,"errorMessage":"Frame #${position} could not be found in the image","messagePattern":"Frame #(.+?) could not be found in the image","errorType":"exception","errorClass":"InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"src/Drivers/Gd/Core.php","lineNumber":76,"sourceCode":"    {\n        $this->clear()->push(new Frame($native));\n\n        return $this;\n    }\n\n    /**\n     * {@inheritdoc}\n     *\n     * @see CoreInterface::frame()\n     *\n     * @throws InvalidArgumentException\n     */\n    public function frame(int $position): FrameInterface\n    {\n        $frame = $this->at($position);\n\n        if ($frame === null) {\n            throw new InvalidArgumentException('Frame #' . $position . ' could not be found in the image');\n        }\n\n        return $frame;\n    }\n\n    /**\n     * {@inheritdoc}\n     *\n     * @see CoreInterface::loops()\n     */\n    public function loops(): int\n    {\n        return $this->loops;\n    }\n\n    /**\n     * {@inheritdoc}\n     *","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/Intervention/image/blob/5598b9e39751c34afc5cdee84abef77f92c26f68/src/Drivers/Gd/Core.php#L58-L94","documentation":"Core::frame($position) looks up the frame collection with at() and requires a hit. Under the GD driver the core holds multiple frames only for animated GIF decodes; any other image has exactly one frame at position 0. Requesting any other position — including 1 — throws this InvalidArgumentException naming the missing index.","triggerScenarios":"$image->core()->frame(1) or higher on a static JPEG/PNG/WebP; looping frame($i++) over an image without checking the frame count; assuming Imagick-style multi-frame cores (TIFF/animated WebP) exist under GD.","commonSituations":"Generic animation-handling code run against the GD driver, which only animates GIFs; off-by-one loops written as for ($i = 1; $i <= $count; $i++); processing animated GIFs after an operation collapsed the core to a single frame.","solutions":["Check the count first: $image->core()->count() and iterate for ($i = 0; $i < $count; $i++)","Remember positions are 0-based — the first frame is frame(0)","For formats other than GIF under the GD driver, treat the image as single-frame; switch to the Imagick driver if you need TIFF/animated WebP frames"],"exampleFix":"// before\nfor ($i = 0; $i <= $image->core()->count(); $i++) {\n    $frame = $image->core()->frame($i); // throws on last iteration\n}\n\n// after\nfor ($i = 0, $n = $image->core()->count(); $i < $n; $i++) {\n    $frame = $image->core()->frame($i);\n}","handlingStrategy":"validation","validationCode":"$position = max(0, $position);\nif ($position >= $image->core()->count()) {\n    // frame does not exist; static GD images only have frame 0\n    $position = 0;\n}","typeGuard":null,"tryCatchPattern":"use Intervention\\Image\\Exceptions\\InvalidArgumentException;\n\ntry {\n    $frame = $image->core()->frame($i);\n} catch (InvalidArgumentException $e) {\n    $frame = $image->core()->first(); // graceful single-frame fallback\n}","preventionTips":["Always compare against $image->core()->count() before frame()","Use 0-based frame positions; the first frame is 0","Assume single-frame cores under the GD driver unless the origin was an animated GIF"],"tags":["gd","frames","animation","out-of-bounds","gif"],"backgroundTag":"index-out-of-bounds","analyzedSha":"5598b9e39751c34afc5cdee84abef77f92c26f68","analyzedAt":"2026-08-23T02:17:31.068Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}