infiniflow/ragflow · warning · ValueError

page_size must be less than or equal to {REST_API_MAX_PAGE_S

Error message

page_size must be less than or equal to {REST_API_MAX_PAGE_SIZE}

What it means

Raised by validate_rest_api_page_size when the requested page_size exceeds REST_API_MAX_PAGE_SIZE (100). Values that are non-numeric or < 1 silently fall back to DEFAULT_PAGE_SIZE (30), but an explicit oversized value is rejected with ValueError to prevent unbounded result sets.

Source

Thrown at api/utils/pagination_utils.py:43

    try:
        int_page = int(page)
    except (TypeError, ValueError):
        return DEFAULT_PAGE
    if int_page < 1:
        return DEFAULT_PAGE
    return int_page


def validate_rest_api_page_size(page_size) -> int:
    """Validate page_size, if invalid, silent fallback to default page_size, and validate it against the public maximum."""
    try:
        int_page_size = int(page_size)
    except (TypeError, ValueError):
        return DEFAULT_PAGE_SIZE
    if int_page_size < 1:
        return DEFAULT_PAGE_SIZE
    if int_page_size > REST_API_MAX_PAGE_SIZE:
        raise ValueError(f"page_size must be less than or equal to {REST_API_MAX_PAGE_SIZE}")
    return int_page_size


def validate_rest_api_ids(ids: list | None, field_name: str = "ids") -> list | None:
    """Validate REST API ID lists against the public maximum."""
    if ids is not None and len(ids) > REST_API_MAX_IDS:
        raise ValueError(f"{field_name} must contain at most {REST_API_MAX_IDS} IDs")
    return ids

View on GitHub (pinned to 554fb1133a)

Solutions

1. Cap page_size at 100 in the client and paginate with increasing page numbers instead.
2. If you legitimately need more rows per call, use filter/ids narrowing or the bulk endpoints rather than a huge page_size.
3. Handle the ValueError (typically surfaced as 400) by clamping to the max and retrying.

Example fix

# before
resp = sdk.list_documents(kb_id, page_size=500)  # ValueError

# after
page_size = min(requested, 100)
resp = sdk.list_documents(kb_id, page_size=page_size, page=page)

page_size = min(int(page_size or 30), 100)  # clamp before the call
resp = sdk.list_documents(kb_id, page=page, page_size=page_size)

def is_valid_page_size(page_size: int) -> bool:
    return isinstance(page_size, int) and 1 <= page_size <= 100

try:
    resp = list_endpoint(page=page, page_size=page_size)
except ValueError as e:
    if 'page_size' in str(e):
        resp = list_endpoint(page=page, page_size=100)
    else:
        raise

When it happens

Trigger: Calling a paginated REST API (dataset/document/chat listings) with ?page_size=101 or larger; SDK or MCP clients ported from internal endpoints that allowed bigger pages.

Common situations: Clients raising page_size to reduce round-trips; porting pagination params from v0 SDK defaults; scripts iterating large datasets with naive page-size math.

Related errors

• {field_name} must contain at most {REST_API_MAX_IDS} IDs
• invalid_uuid_format
• main() must be defined or exported.
• main() must return a value. Use null for an empty result.
• main() returned a non-JSON-serializable value.

AI-assisted analysis of infiniflow/ragflow@554fb1133a (2026-08-15). Data as JSON: /api/errors/62f5106605fae001. Report an issue: GitHub.