{"record":{"id":"a7c2647a66621a8a","repo":"VectifyAI/PageIndex","slug":"failed-to-list-documents-folders-are-not-supporte","errorCode":null,"errorMessage":"Failed to list documents: folders are not supported in local mode.","messagePattern":"Failed to list documents: folders are not supported in local mode\\.","errorType":"exception","errorClass":"PageIndexAPIError","httpStatus":null,"severity":"error","filePath":"pageindex/local_api.py","lineNumber":356,"sourceCode":"                (\"id\", \"name\", \"description\", \"status\", \"createdAt\", \"pageNum\", \"folderId\")}\n\n    def delete_document(self, doc_id: str) -> dict[str, Any]:\n        if not self._store.delete_document(doc_id):\n            raise PageIndexAPIError(\"Failed to delete document: Document not found.\")\n        return {\"message\": \"Document deleted successfully.\"}\n\n    def list_documents(\n        self,\n        limit: int = 50,\n        offset: int = 0,\n        folder_id: str | None = None,\n    ) -> dict[str, Any]:\n        if limit < 1 or limit > 100:\n            raise ValueError(\"limit must be between 1 and 100\")\n        if offset < 0:\n            raise ValueError(\"offset must be non-negative\")\n        if folder_id is not None:\n            raise PageIndexAPIError(\n                \"Failed to list documents: folders are not supported in local mode.\"\n            )\n        metas = sorted(self._store.list_metas(), key=lambda m: m.get(\"id\") or \"\")\n        metas.sort(key=lambda m: m.get(\"createdAt\") or \"\", reverse=True)\n        documents = [{\n            \"id\": m.get(\"id\"),\n            \"name\": m.get(\"name\"),\n            \"description\": m.get(\"description\"),\n            \"status\": m.get(\"status\"),\n            \"createdAt\": m.get(\"createdAt\"),\n            \"pageNum\": m.get(\"pageNum\", 0),\n            \"folderId\": None,\n            \"metadata\": m.get(\"metadata\"),\n            \"features\": {},\n        } for m in metas[offset:offset + limit]]\n        return {\n            \"documents\": documents,\n            \"total\": len(metas),","sourceCodeStart":338,"sourceCodeEnd":374,"githubUrl":"https://github.com/VectifyAI/PageIndex/blob/afb5e119766630af6014b04fe8b53357527bc05e/pageindex/local_api.py#L338-L374","documentation":"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.","triggerScenarios":"Calling client.list_documents(folder_id=\"fld_x\") on a client constructed in local mode (local store / no cloud project).","commonSituations":"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.","solutions":["Branch on mode: only pass folder_id when using the cloud client","Filter locally: [d for d in client.list_documents()['documents'] if d.get('folderId') == folder_id]","Check the client type/config before building the call"],"exampleFix":"# before\nclient.list_documents(folder_id=fid)\n\n# after\nif fid is None:\n    docs = client.list_documents()\nelse:\n    docs = client.list_documents()  # local mode: filter client-side\n    docs['documents'] = [d for d in docs['documents'] if d.get('folderId') == fid]","handlingStrategy":"type-guard","validationCode":"kwargs = {}\nif folder_id is not None and not is_local_mode(client):\n    kwargs['folder_id'] = folder_id\nclient.list_documents(**kwargs)","typeGuard":"def supports_folders(client) -> bool:\n    return getattr(client, 'api_key', None) is not None  # cloud mode","tryCatchPattern":"try:\n    client.list_documents(folder_id=fid)\nexcept PageIndexAPIError as e:\n    if 'folders are not supported' not in str(e):\n        raise\n    docs = [d for d in client.list_documents()['documents'] if d.get('folderId') == fid]","preventionTips":["Branch request params on deployment mode","Filter folderId client-side in local mode","Document mode-specific parameters in shared code"],"tags":["pageindex","local-mode","folders","unsupported-feature"],"backgroundTag":"unsupported-parameter-in-local-mode","analyzedSha":"afb5e119766630af6014b04fe8b53357527bc05e","analyzedAt":"2026-08-27T11:20:48.519Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}