BerriAI/litellm · error · ValueError

`pages` must be a list[int] (0-based, Mistral-style) or a st

Error message

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

What it means

Catch-all type error for the `pages` parameter of Azure Document Intelligence OCR: the value is neither a str, a list[int], nor a list[str] (e.g. a tuple, a single int, a dict, or a mixed int/str list). LiteLLM only supports those three shapes when mapping Mistral-style OCR params onto Azure's query string, and mixed lists fail all(isinstance(...)) branches.

Source

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

            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").

        Accepted inputs:
          - list[str]: feature names like ["keyValuePairs", "languages"].
          - str: a single feature name or comma-separated names.
        """
        invalid_features_error: Final = ValueError(
            f"Invalid `features` for Azure Document Intelligence: {features!r}. "
            f"Expected a list of feature names or a comma-separated string like "
            f"'keyValuePairs' or 'keyValuePairs,languages'."
        )

        if isinstance(features, str):

View on GitHub (pinned to 6c2dcb801b)

Solutions

  1. Pass one of the supported shapes: str ('1-3,5'), list[int] (0-based), or list[str] (1-based tokens).
  2. For a single page as int, wrap it: [2] or '3'.
  3. Normalize mixed lists to one type before the call (e.g. [str(p) for p in pages] — remembering the 1-based semantics of str tokens).

Example fix

# before
litellm.aocr_document(model=..., document=doc, pages=(0, 1))  # tuple -> unsupported

# after
litellm.aocr_document(model=..., document=doc, pages=[0, 1])  # list[int], 0-based
Defensive patterns

Strategy: type-guard

Validate before calling

def normalize_pages(v):
    if isinstance(v, (list,)) and v and all(isinstance(p, int) and not isinstance(p, bool) for p in v):
        return v
    if isinstance(v, str):
        return v
    if isinstance(v, (tuple, set)):
        return list(v)
    raise TypeError("pages must be str, list[int], or list[str]")

Type guard

def is_supported_pages(v: object) -> bool:
    if isinstance(v, str):
        return True
    if isinstance(v, list) and v:
        return all(isinstance(p, int) and not isinstance(p, bool) for p in v) or all(isinstance(p, str) for p in v)
    return False

Prevention

When it happens

Trigger: Calling azure_ai doc-intelligence OCR with pages=(1, 2) (tuple), pages=3 (bare int), pages={"pages": [1]}, or a mixed list like [1, "3"].

Common situations: Frameworks passing tuples instead of lists; mixed-type lists from untyped configs; assuming a single int page is accepted; pydantic models with Any-typed fields.

Related errors

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