{"record":{"id":"5b3873e3ea7522c2","repo":"docling-project/docling","slug":"page-index-out-of-range-page-no","errorCode":null,"errorMessage":"Page index out of range: {page_no}","messagePattern":"Page index out of range: (.+?)","errorType":"exception","errorClass":"IndexError","httpStatus":null,"severity":"error","filePath":"docling/backend/image_backend.py","lineNumber":186,"sourceCode":"                else:\n                    self._frames.append(img.convert(\"RGB\"))\n        except Exception as e:\n            for frame in self._frames:\n                frame.close()\n            self._frames = []\n            raise DocumentLoadError(\n                f\"Could not load image for document {self.file}\"\n            ) from e\n\n    def is_valid(self) -> bool:\n        return len(self._frames) > 0\n\n    def page_count(self) -> int:\n        return len(self._frames)\n\n    def load_page(self, page_no: int) -> _ImagePageBackend:\n        if not (0 <= page_no < len(self._frames)):\n            raise IndexError(f\"Page index out of range: {page_no}\")\n        return _ImagePageBackend(self._frames[page_no], page_no)\n\n    @classmethod\n    def supported_formats(cls) -> set[InputFormat]:\n        # Only IMAGE here; PDF handling remains in PDF-oriented backends\n        return {InputFormat.IMAGE}\n\n    @classmethod\n    def supports_pagination(cls) -> bool:\n        return True\n\n    def unload(self):\n        for frame in self._frames:\n            frame.close()\n        self._frames = []\n        super().unload()\n","sourceCodeStart":168,"sourceCodeEnd":203,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/backend/image_backend.py#L168-L203","documentation":"ImageDocumentBackend.load_page() raises IndexError when page_no is negative or >= len(self._frames), where frames are the PIL image frames loaded at init (single-frame images have exactly one). It is the standard pagination bounds guard; use page_count() to discover the valid range.","triggerScenarios":"Calling load_page(1) on a single-frame JPEG/PNG; iterating with a stale page count after the backend reloaded; off-by-one loops like range(1, page_count()+1).","commonSituations":"Code written against paginated PDFs reused for images assuming multiple pages; hardcoded page indices; loops that assume page_count() >= 1 even for invalid inputs.","solutions":["Always bound-check: for i in range(backend.page_count()): backend.load_page(i)","Remember single-frame images have exactly one page (index 0)","Handle IndexError per page so one bad index does not abort a batch"],"exampleFix":"# before\npage = backend.load_page(1)  # IndexError on single-frame image\n\n# after\nfor i in range(backend.page_count()):\n    page = backend.load_page(i)","handlingStrategy":"validation","validationCode":"n = backend.page_count()\nassert 0 <= page_no < n, f'page {page_no} out of range 0..{n - 1}'","typeGuard":"def valid_page(backend, page_no: int) -> bool:\n    return 0 <= page_no < backend.page_count()","tryCatchPattern":"try:\n    page = backend.load_page(i)\nexcept IndexError:\n    log.warning('page %d missing (count=%d), skipping', i, backend.page_count())\n    continue","preventionTips":["Always iterate range(page_count()) from 0","Remember single-frame images expose exactly one page"],"tags":["image","pagination","bounds-check"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}