VectifyAI/PageIndex · error · ValueError

limit must be between 1 and 100

Error message

limit must be between 1 and 100

What it means

list_documents validates pagination bounds before querying the store: limit must be an integer in [1, 100]. It raises ValueError (not PageIndexAPIError) so bad arguments surface as programmer errors rather than API failures.

Source

Thrown at pageindex/local_api.py:352

        meta = self._store.get_meta(doc_id)
        if meta is None:
            raise PageIndexAPIError("Failed to get document metadata: Document not found")
        return {key: meta.get(key) for key in
                ("id", "name", "description", "status", "createdAt", "pageNum", "folderId")}

    def delete_document(self, doc_id: str) -> dict[str, Any]:
        if not self._store.delete_document(doc_id):
            raise PageIndexAPIError("Failed to delete document: Document not found.")
        return {"message": "Document deleted successfully."}

    def list_documents(
        self,
        limit: int = 50,
        offset: int = 0,
        folder_id: str | None = None,
    ) -> dict[str, Any]:
        if limit < 1 or limit > 100:
            raise ValueError("limit must be between 1 and 100")
        if offset < 0:
            raise ValueError("offset must be non-negative")
        if folder_id is not None:
            raise PageIndexAPIError(
                "Failed to list documents: folders are not supported in local mode."
            )
        metas = sorted(self._store.list_metas(), key=lambda m: m.get("id") or "")
        metas.sort(key=lambda m: m.get("createdAt") or "", reverse=True)
        documents = [{
            "id": m.get("id"),
            "name": m.get("name"),
            "description": m.get("description"),
            "status": m.get("status"),
            "createdAt": m.get("createdAt"),
            "pageNum": m.get("pageNum", 0),
            "folderId": None,
            "metadata": m.get("metadata"),
            "features": {},

View on GitHub (pinned to afb5e11976)

Solutions

1. Clamp limit to the 1-100 window, e.g. limit = max(1, min(100, desired))
2. Page through results with limit=100 and increasing offset instead of one big limit
3. Validate user-supplied page sizes at your API boundary before forwarding

Example fix

# before
client.list_documents(limit=500)

# after
client.list_documents(limit=100, offset=0)  # page in chunks of 100

limit = max(1, min(100, int(limit or 50)))
docs = client.list_documents(limit=limit, offset=offset)

def is_valid_limit(limit) -> bool:
    return isinstance(limit, int) and not isinstance(limit, bool) and 1 <= limit <= 100

null

When it happens

Trigger: Calling list_documents(limit=0), limit=-5, limit=101, or limit=200 expecting full listing.

Common situations: Porting code from an API with different page-size caps, hardcoding large limits for 'give me everything', passing limit computed as len(items) that can exceed 100.

Related errors

• offset must be non-negative
• system message content must be a string or a list of text pa
• messages must be a non-empty list.
• Each message must be a dict with 'role' and 'content'.
• chat_completions content must be a string; for structured it

AI-assisted analysis of VectifyAI/PageIndex@afb5e11976 (2026-08-27). Data as JSON: /api/errors/950f02e0de3b7dc6. Report an issue: GitHub.