HKUDS/DeepTutor · error · RuntimeError

PageIndex API key is not configured. Add it under Knowledge

Error message

PageIndex API key is not configured. Add it under Knowledge → RAG pipeline settings before using a PageIndex knowledge base.

What it means

PageIndexConfig creation failed because the PageIndex API key is empty. get_pageindex_config(require_key=True) loads settings via the runtime settings service and raises when no api_key is set, since cloud PageIndex KBs cannot authenticate without it.

Source

Thrown at deeptutor/services/rag/pipelines/pageindex/config.py:30


@dataclass(frozen=True)
class PageIndexConfig:
    api_key: str


def get_pageindex_config(*, require_key: bool = True) -> PageIndexConfig:
    """Load the active PageIndex credential.

    Raises when ``require_key`` and the key is empty, so callers fail with a
    clear, actionable message instead of an opaque 401 from the API.
    """
    from deeptutor.services.config import get_runtime_settings_service

    settings = get_runtime_settings_service().load_pageindex()
    api_key = str(settings.get("api_key") or "").strip()
    if require_key and not api_key:
        raise RuntimeError(
            "PageIndex API key is not configured. Add it under "
            "Knowledge → RAG pipeline settings before using a PageIndex knowledge base."
        )
    return PageIndexConfig(api_key=api_key)


def is_pageindex_configured() -> bool:
    """Best-effort check used to flag the provider as ready in the UI."""
    try:
        return bool(get_pageindex_config(require_key=False).api_key)
    except Exception:
        return False


__all__ = [
    "PageIndexConfig",
    "get_pageindex_config",
    "is_pageindex_configured",

View on GitHub (pinned to 3e82f13042)

Solutions

Open Knowledge → RAG pipeline settings and enter the PageIndex API key (or set pageindex.api_key in data/user/settings/*.json / process-env override)
Verify with is_pageindex_configured() / get_pageindex_config(require_key=False) before attempting cloud operations
If you intend to run fully local, use the OSS provider path instead of the cloud client

Example fix

// before
cfg = get_pageindex_config()  # RuntimeError
// after
if not is_pageindex_configured():
    raise SystemExit("Configure PageIndex API key first")
cfg = get_pageindex_config()

Defensive patterns

Strategy: validation

Validate before calling

from deeptutor.services.rag.pipelines.pageindex.config import get_pageindex_config
cfg = get_pageindex_config(require_key=False)
if not cfg.api_key:
    raise SystemExit("Configure the PageIndex API key first")

Try / catch

try:
    cfg = get_pageindex_config()
except RuntimeError as e:
    if "PageIndex API key" in str(e):
        # prompt user to configure, degrade, or abort
        ...

Prevention

Check is_pageindex_configured() before exposing PageIndex KB options in the UI
Store the api_key via the settings UI rather than hand-editing JSON
Fail fast at app startup when PageIndex is the default pipeline

When it happens

Trigger: Calling get_pageindex_config(require_key=True) or any code path that preflights/creates a cloud PageIndex knowledge base (is_pageindex_configured, _pageindex_preflight) before an api_key has been saved in Knowledge → RAG pipeline settings.

Common situations: Fresh installs where PageIndex was never configured; settings JSON under data/user/settings missing the pageindex.api_key entry; switching from OSS/local library mode to cloud mode without adding a key; key stored under a different profile.

Understand the failure class

Background: "API key is required" / "API key not found" / "No API key was set": the missing-api-key error family across 16 libraries — this error's family across 16 libraries.

Related errors

AI-assisted analysis of HKUDS/DeepTutor@3e82f13042 (2026-08-27). Data as JSON: /api/errors/21f0608a271c9ba4. Report an issue: GitHub.