VectifyAI/PageIndex · error · PageIndexAPIError

chat declares mode "cloud" but carries ({keys}) — the manage

Error message

chat declares mode "cloud" but carries ({keys}) — the managed chat selects its own model. Drop the mode, or the keys.

What it means

The chat dict declared {"mode": "cloud"} (managed chat) but also carried "model"/"backend" keys. The managed cloud chat picks its own model, so user-supplied model settings contradict the declaration; the SDK refuses to guess which wins.

Source

Thrown at pageindex/client.py:212

            return "own", {"chat_model": chat}
        raise PageIndexAPIError(
            "chat is an empty string — pass a model name, or "
            '"cloud" for the managed chat.')
    if isinstance(chat, Mapping):
        # None-valued keys mean "absent", exactly like the flat arguments.
        conf = {name: value for name, value in chat.items()
                if value is not None}
        declared = _declared_mode(conf.pop("mode", None), "chat")
        unknown = set(conf) - {"model", "backend"}
        if (not conf and declared is None) or unknown:
            raise PageIndexAPIError(
                ("chat is an empty dict" if not conf else
                 f"Unknown chat keys ({', '.join(sorted(unknown))})")
                + ' — chat takes "model" and "backend" (your own model), '
                'or {"mode": "cloud"} / "cloud" for the managed chat.')
        if declared == "cloud":
            if conf:
                raise PageIndexAPIError(
                    'chat declares mode "cloud" but carries '
                    f"({', '.join(sorted(conf))}) — the managed chat "
                    "selects its own model. Drop the mode, or the keys.")
            return "managed", {}
        mapped = {"chat_model": conf.get("model"),
                  "chat_backend": conf.get("backend")}
        return "own", {name: value for name, value in mapped.items()
                       if value is not None}
    raise PageIndexAPIError("chat must be a string or a dict.")


class PageIndexClient:
    """
    Python SDK client for PageIndex.

    Two independent sides, each locally run or cloud-managed:

    - **index** — where documents live. With an ``api_key`` they live in

View on GitHub (pinned to afb5e11976)

Solutions

1. For the managed chat, keep only {"mode": "cloud"}
2. To use your own model, drop the "mode" key and keep "model"/"backend"

Example fix

# before
PageIndexClient(chat={"mode": "cloud", "model": "gpt-4o-mini"})
# after
PageIndexClient(chat={"mode": "cloud"})

if chat.get("mode") == "cloud":
    chat = {k: v for k, v in chat.items() if k == "mode"}  # strip model/backend

def cloud_mode_is_clean(d: dict) -> bool:
    return not (d.get("mode") == "cloud" and set(d) - {"mode"})

When it happens

Trigger: PageIndexClient(chat={"mode": "cloud", "model": "gpt-4o-mini"}) or chat={"mode": "cloud", "backend": {...}}).

Common situations: Starting from an own-model config and adding mode: cloud to "switch" without removing the old keys; config templates that pre-fill a model alongside a mode field.

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 must be a string or a dict.
• model= sets both roles at once, so no slot can absorb it — n

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