docling-project/docling · error · IndexError

Page index out of range: {page_no}

Error message

Page index out of range: {page_no}

What it means

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.

Source

Thrown at docling/backend/image_backend.py:186

                else:
                    self._frames.append(img.convert("RGB"))
        except Exception as e:
            for frame in self._frames:
                frame.close()
            self._frames = []
            raise DocumentLoadError(
                f"Could not load image for document {self.file}"
            ) from e

    def is_valid(self) -> bool:
        return len(self._frames) > 0

    def page_count(self) -> int:
        return len(self._frames)

    def load_page(self, page_no: int) -> _ImagePageBackend:
        if not (0 <= page_no < len(self._frames)):
            raise IndexError(f"Page index out of range: {page_no}")
        return _ImagePageBackend(self._frames[page_no], page_no)

    @classmethod
    def supported_formats(cls) -> set[InputFormat]:
        # Only IMAGE here; PDF handling remains in PDF-oriented backends
        return {InputFormat.IMAGE}

    @classmethod
    def supports_pagination(cls) -> bool:
        return True

    def unload(self):
        for frame in self._frames:
            frame.close()
        self._frames = []
        super().unload()

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Always bound-check: for i in range(backend.page_count()): backend.load_page(i)
2. Remember single-frame images have exactly one page (index 0)
3. Handle IndexError per page so one bad index does not abort a batch

Example fix

# before
page = backend.load_page(1)  # IndexError on single-frame image

# after
for i in range(backend.page_count()):
    page = backend.load_page(i)

n = backend.page_count()
assert 0 <= page_no < n, f'page {page_no} out of range 0..{n - 1}'

def valid_page(backend, page_no: int) -> bool:
    return 0 <= page_no < backend.page_count()

try:
    page = backend.load_page(i)
except IndexError:
    log.warning('page %d missing (count=%d), skipping', i, backend.page_count())
    continue

When it happens

Trigger: 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).

Common situations: Code written against paginated PDFs reused for images assuming multiple pages; hardcoded page indices; loops that assume page_count() >= 1 even for invalid inputs.

Related errors

• Incompatible file format {self.input_format} was passed to I
• Could not load image for document {self.file}
• Page image dimensions {im.size} do not match page geometry (
• Image file {image_info.path} exceeds individual file size li
• Unsupported numpy array shape: {image.shape}

AI-assisted analysis of docling-project/docling@61d76f1ff3 (2026-08-14). Data as JSON: /api/errors/5b3873e3ea7522c2. Report an issue: GitHub.