VectifyAI/PageIndex · error · PageIndexAPIError

chat is an empty string — pass a model name, or "cloud" for

Error message

chat is an empty string — pass a model name, or "cloud" for the managed chat.

What it means

The chat argument was a string, but blank (empty or whitespace-only) after checking it isn't a reserved mode word. The library rejects it because an empty model name would configure nothing and the intended mode (own model vs managed cloud chat) becomes ambiguous. Pass a real model name or the string "cloud".

Source

Thrown at pageindex/client.py:195


def _resolve_chat_slot(chat) -> "tuple[Optional[str], dict[str, Any]]":
    """The ``chat=`` slot as (mode, own-model overrides) — mode is
    "managed", "own", or None (nothing declared beyond the overrides)."""
    from .types import PAGEINDEX_CLOUD
    if isinstance(chat, str):
        word = chat.strip().lower()
        if word in (PAGEINDEX_CLOUD, "cloud"):
            return "managed", {}
        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 '

View on GitHub (pinned to afb5e11976)

Solutions

Pass a real model name, e.g. chat="gpt-4o-mini" (or "cloud" for the managed chat)
If the value comes from an env var, guard it: chat=os.environ.get("CHAT_MODEL") or "cloud"
Drop the chat argument entirely if you don't want to configure the chat side

Example fix

# before
PageIndexClient(chat=os.getenv("CHAT_MODEL", ""))
# after
PageIndexClient(chat=os.getenv("CHAT_MODEL") or "cloud")

Defensive patterns

Strategy: validation

Validate before calling

chat = os.getenv("CHAT_MODEL")
if chat is not None and not chat.strip():
    chat = "cloud"  # or raise
client = PageIndexClient(chat=chat)

Type guard

def valid_chat_str(chat: str) -> bool:
    return isinstance(chat, str) and bool(chat.strip())

Prevention

Never default env lookups to "" — use os.getenv(...) which returns None
Normalize empty/whitespace strings to None before passing them to the client

When it happens

Trigger: Calling PageIndexClient(chat=""), chat=" ", or passing chat=os.getenv("CHAT_MODEL") when the env var is unset (yields "").

Common situations: Reading the chat model from an environment variable that is not set; copy-pasting a config template with a placeholder left empty; programmatically building kwargs where the model field defaults to "".

Related errors

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