{"record":{"id":"6093c0660e6aca3f","repo":"VectifyAI/PageIndex","slug":"mode-local-disagrees-with-index-that-index-se","errorCode":null,"errorMessage":"mode=\"local\" disagrees with index= — that index selects cloud documents. Drop one of them.","messagePattern":"mode=\"local\" disagrees with index= — that index selects cloud documents\\. Drop one of them\\.","errorType":"validation","errorClass":"PageIndexAPIError","httpStatus":null,"severity":"error","filePath":"pageindex/client.py","lineNumber":400,"sourceCode":"            raise PageIndexAPIError(\n                \"index= and the flat index-side arguments \"\n                f\"({', '.join(sorted(index_flat))}) are two spellings of \"\n                \"the same thing — use one or the other.\")\n        if chat is not None and chat_flat:\n            raise PageIndexAPIError(\n                \"chat= and the flat chat-side arguments \"\n                f\"({', '.join(sorted(chat_flat))}) are two spellings of \"\n                \"the same thing — use one or the other.\")\n        # ``mode=`` is a cross-check, not a spelling: it combines with\n        # either spelling of the index side and must agree with it. The\n        # pinned classes declare the side by class; their errors name the\n        # class, never a mode= the user did not write.\n        declared = _declared_mode(mode, \"client\") or self._pin\n        pinned = type(self).__name__ if self._pin else None\n        if index is not None:\n            cloud_key, index_conf = _resolve_index_slot(index)\n            if declared == \"local\" and cloud_key is not None:\n                raise PageIndexAPIError(\n                    f\"{pinned} pins local documents — that index= selects \"\n                    \"cloud documents. Drop it, or use PageIndexCloudClient.\"\n                    if pinned else\n                    'mode=\"local\" disagrees with index= — that index '\n                    \"selects cloud documents. Drop one of them.\")\n            if declared == \"cloud\" and cloud_key is None:\n                raise PageIndexAPIError(\n                    f\"{pinned} pins cloud documents — that index= \"\n                    \"configures the local store. Drop it, or use \"\n                    \"PageIndexLocalClient.\"\n                    if pinned else\n                    'mode=\"cloud\" disagrees with index= — that index '\n                    \"configures the local store. Drop one of them.\")\n            if callable(cloud_key):\n                cloud_key = cloud_key()\n        else:\n            cloud_key = api_key\n            if declared == \"local\" and api_key is not None:","sourceCodeStart":382,"sourceCodeEnd":418,"githubUrl":"https://github.com/VectifyAI/PageIndex/blob/afb5e119766630af6014b04fe8b53357527bc05e/pageindex/client.py#L382-L418","documentation":"mode=\"local\" was passed explicitly, but the index= slot selects cloud documents (it contains an api_key or cloud declaration). mode is a cross-check that must agree with the index configuration; a contradiction means the call is ambiguous about where documents live.","triggerScenarios":"PageIndexClient(mode=\"local\", index={\"api_key\": KEY}) or mode=\"local\" with index=\"cloud\").","commonSituations":"Hardcoding mode from an old local setup while migrating the index config to cloud; leftover mode kwarg in shared helper functions.","solutions":["Drop mode=\"local\" if cloud documents are intended","Or drop the cloud-selecting key (api_key / cloud declaration) from index= if local is intended"],"exampleFix":"# before\nPageIndexClient(mode=\"local\", index={\"api_key\": KEY})\n# after\nPageIndexClient(index={\"api_key\": KEY})","handlingStrategy":"validation","validationCode":"if mode == \"local\":\n    assert not (index and cloud_selecting_key(index)), \"mode=local conflicts with cloud index=\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Omit mode= entirely and let the index config / api_key declare the document source","Derive mode from config instead of hardcoding it when index config is user-supplied"],"tags":["config","mode","local-vs-cloud"],"backgroundTag":"conflicting-config-options","analyzedSha":"afb5e119766630af6014b04fe8b53357527bc05e","analyzedAt":"2026-08-27T11:20:48.519Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}