VectifyAI/PageIndex · error · PageIndexAPIError

Failed to list documents: folders are not supported in local

Error message

Failed to list documents: folders are not supported in local mode.

What it means

The local (non-cloud) PageIndex mode has no folder concept; passing folder_id to list_documents is explicitly rejected. Folder filtering exists only on the managed/cloud API surface.

Source

Thrown at pageindex/local_api.py:356

                ("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": {},
        } for m in metas[offset:offset + limit]]
        return {
            "documents": documents,
            "total": len(metas),

View on GitHub (pinned to afb5e11976)

Solutions

1. Branch on mode: only pass folder_id when using the cloud client
2. Filter locally: [d for d in client.list_documents()['documents'] if d.get('folderId') == folder_id]
3. Check the client type/config before building the call

Example fix

# before
client.list_documents(folder_id=fid)

# after
if fid is None:
    docs = client.list_documents()
else:
    docs = client.list_documents()  # local mode: filter client-side
    docs['documents'] = [d for d in docs['documents'] if d.get('folderId') == fid]

kwargs = {}
if folder_id is not None and not is_local_mode(client):
    kwargs['folder_id'] = folder_id
client.list_documents(**kwargs)

def supports_folders(client) -> bool:
    return getattr(client, 'api_key', None) is not None  # cloud mode

try:
    client.list_documents(folder_id=fid)
except PageIndexAPIError as e:
    if 'folders are not supported' not in str(e):
        raise
    docs = [d for d in client.list_documents()['documents'] if d.get('folderId') == fid]

When it happens

Trigger: Calling client.list_documents(folder_id="fld_x") on a client constructed in local mode (local store / no cloud project).

Common situations: Sharing request-handling code between a cloud deployment and a local/offline build, migrating from cloud API to local mode without stripping folder parameters, frontend sending folder filters unconditionally.

Related errors

• Failed to delete document: Document not found.
• limit must be between 1 and 100
• offset must be non-negative
• doc_id must be a string or a list of strings.
• system message content must be a string or a list of text pa

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