BerriAI/litellm · error · ValueError

`pages` integers must be >= 0 (Mistral 0-based indices)

Error message

`pages` integers must be >= 0 (Mistral 0-based indices)

What it means

Raised when `pages` is a list of integers but at least one is negative. LiteLLM treats list[int] input as Mistral-style 0-based page indices and converts them to Azure's 1-based format, so negative values have no valid meaning and are rejected before the request. The check runs during request transformation, ahead of any Azure call.

Source

Thrown at litellm/llms/azure_ai/ocr/document_intelligence/transformation.py:158

        """
        pages_pattern: Final = re.compile(r"^\s*\d+(-\d+)?(\s*,\s*\d+(-\d+)?)*\s*$")

        if isinstance(pages, str):
            if not pages_pattern.match(pages):
                raise ValueError(
                    f"Invalid `pages` string for Azure Document Intelligence: "
                    f"{pages!r}. Expected format like '1-3,5,7-9'."
                )
            return pages.replace(" ", "")

        if isinstance(pages, list):
            if len(pages) == 0:
                return ""
            if any(isinstance(p, bool) for p in pages):
                raise ValueError("`pages` must be integers, not booleans")
            if all(isinstance(p, int) for p in pages):
                if any(p < 0 for p in pages):
                    raise ValueError("`pages` integers must be >= 0 (Mistral 0-based indices)")
                # Mistral 0-based -> Azure 1-based.
                return ",".join(str(p + 1) for p in sorted(set(pages)))
            if all(isinstance(p, str) for p in pages):
                joined: Final = ",".join(p.strip() for p in pages)
                if not pages_pattern.match(joined):
                    raise ValueError(
                        f"Invalid `pages` list for Azure Document Intelligence: "
                        f"{pages!r}. Expected tokens like '1' or '3-5'."
                    )
                return joined

        raise ValueError("`pages` must be a list[int] (0-based, Mistral-style) or a string like '1-3,5,7-9'.")

    @staticmethod
    def _normalize_features_param(features: object) -> str:
        """
        Convert a caller-provided `features` value to Azure DI's query-string
        form (comma-joined feature names, e.g. "keyValuePairs,languages").

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Use non-negative 0-based indices: [0, 1, 2] means pages 1-3 in Azure terms.
2. If you meant 1-based Azure pages, pass a string like '1-3' instead of a list.
3. Clamp or validate computed indices (e.g. max(p, 0)) before the call.

Example fix

# before
pages = [current_page - 1 for current_page in selected]  # selected[0]==0 -> -1
litellm.aocr_document(model=..., document=doc, pages=pages)

# after
pages = [max(p, 0) for p in (current_page - 1 for current_page in selected)]
litellm.aocr_document(model=..., document=doc, pages=pages)

def valid_page_indices(pages: list[int]) -> bool:
    return all(p >= 0 for p in pages if isinstance(p, int) and not isinstance(p, bool))

When it happens

Trigger: Calling azure_ai doc-intelligence OCR with optional_params={"pages": [0, -1]} or pages=[-1] — any list[int] containing a value < 0.

Common situations: Off-by-one bugs where code computes page indices with a -1 adjustment and undershoots; parsing user input like '-1' into ints; mixing up 0-based and 1-based conventions and trying to compensate.

Related errors

• Invalid `pages` string for Azure Document Intelligence: {pag
• Invalid `pages` list for Azure Document Intelligence: {pages
• `pages` must be integers, not booleans
• `pages` must be a list[int] (0-based, Mistral-style) or a st
• Expected document dict, got {type(document)}

AI-assisted analysis of BerriAI/litellm@6c2dcb801b (2026-08-15). Data as JSON: /api/errors/edbd1f86e37317d8. Report an issue: GitHub.