VectifyAI/PageIndex · error · PageIndexAPIError

Unknown chat keys ({keys}) — chat takes "model" and "backend

Error message

Unknown chat keys ({keys}) — chat takes "model" and "backend" (your own model), or {"mode": "cloud"} / "cloud" for the managed chat.

What it means

The chat dict contained keys other than the allowed "model", "backend", and "mode". The SDK strictly validates the slot's schema so typos and stale option names fail fast instead of being silently ignored.

Source

Thrown at pageindex/client.py:205

        if word == "local":
            return "own", {}
        if word in _RESERVED_MODE_WORDS:
            raise PageIndexAPIError(
                f'chat="{chat}" is not a mode word — the managed chat is '
                'chat="cloud".')
        if chat.strip():
            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.")

View on GitHub (pinned to afb5e11976)

Solutions

1. Rename unknown keys to the supported ones: only "model", "backend", and "mode" are accepted
2. Move provider-specific options (temperature, api_key, etc.) inside the "backend" dict
3. Check the error message — it lists exactly which keys are unknown

Example fix

# before
PageIndexClient(chat={"model": "gpt-4o-mini", "temperature": 0.2})
# after
PageIndexClient(chat={"model": "gpt-4o-mini", "backend": {"temperature": 0.2}})

ALLOWED = {"model", "backend", "mode"}
assert set(chat_dict) <= ALLOWED, f"bad chat keys: {set(chat_dict) - ALLOWED}"

def chat_keys_valid(d: dict) -> bool:
    return set(d) <= {"model", "backend", "mode"}

When it happens

Trigger: PageIndexClient(chat={"model": "x", "temperature": 0.2}) or chat={"models": "x"} (typo), or passing a raw provider kwargs dict (e.g. OpenAI params) as chat.

Common situations: Typos like "models" or "name"; upgrading from an older SDK version that accepted different keys; pasting provider-specific option dicts into the chat slot.

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
• chat declares mode "cloud" but carries ({keys}) — the manage
• chat must be a string or a dict.
• chat= and the flat chat-side arguments ({args}) are two spel

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