VectifyAI/PageIndex · error · PageIndexAPIError

mode="local" disagrees with index= — that index selects clou

Error message

mode="local" disagrees with index= — that index selects cloud documents. Drop one of them.

What it means

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.

Source

Thrown at pageindex/client.py:400

            raise PageIndexAPIError(
                "index= and the flat index-side arguments "
                f"({', '.join(sorted(index_flat))}) are two spellings of "
                "the same thing — use one or the other.")
        if chat is not None and chat_flat:
            raise PageIndexAPIError(
                "chat= and the flat chat-side arguments "
                f"({', '.join(sorted(chat_flat))}) are two spellings of "
                "the same thing — use one or the other.")
        # ``mode=`` is a cross-check, not a spelling: it combines with
        # either spelling of the index side and must agree with it. The
        # pinned classes declare the side by class; their errors name the
        # class, never a mode= the user did not write.
        declared = _declared_mode(mode, "client") or self._pin
        pinned = type(self).__name__ if self._pin else None
        if index is not None:
            cloud_key, index_conf = _resolve_index_slot(index)
            if declared == "local" and cloud_key is not None:
                raise PageIndexAPIError(
                    f"{pinned} pins local documents — that index= selects "
                    "cloud documents. Drop it, or use PageIndexCloudClient."
                    if pinned else
                    'mode="local" disagrees with index= — that index '
                    "selects cloud documents. Drop one of them.")
            if declared == "cloud" and cloud_key is None:
                raise PageIndexAPIError(
                    f"{pinned} pins cloud documents — that index= "
                    "configures the local store. Drop it, or use "
                    "PageIndexLocalClient."
                    if pinned else
                    'mode="cloud" disagrees with index= — that index '
                    "configures the local store. Drop one of them.")
            if callable(cloud_key):
                cloud_key = cloud_key()
        else:
            cloud_key = api_key
            if declared == "local" and api_key is not None:

View on GitHub (pinned to afb5e11976)

Solutions

1. Drop mode="local" if cloud documents are intended
2. Or drop the cloud-selecting key (api_key / cloud declaration) from index= if local is intended

Example fix

# before
PageIndexClient(mode="local", index={"api_key": KEY})
# after
PageIndexClient(index={"api_key": KEY})

if mode == "local":
    assert not (index and cloud_selecting_key(index)), "mode=local conflicts with cloud index="

When it happens

Trigger: PageIndexClient(mode="local", index={"api_key": KEY}) or mode="local" with index="cloud").

Common situations: Hardcoding mode from an old local setup while migrating the index config to cloud; leftover mode kwarg in shared helper functions.

Related errors

• chat is an empty string — pass a model name, or "cloud" for
• chat is an empty dict — chat takes "model" and "backend" (yo
• Unknown chat keys ({keys}) — chat takes "model" and "backend
• chat declares mode "cloud" but carries ({keys}) — the manage
• chat must be a string or a dict.

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