HKUDS/DeepTutor · error · HTTPException

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 creating a PageIndex knowledge base.

What it means

Raised by the provider preflight _assert_provider_ready when the selected RAG provider is PageIndex and is_pageindex_configured() returns False — no API key is present in the runtime settings. Creation/upload/reindex for PageIndex KBs is blocked with HTTP 400 before any work starts.

Source

Thrown at deeptutor/api/routers/knowledge.py:655

    Empty / legacy / unknown strings coerce to the default (so a stale config or
    a removed engine never selects a missing pipeline). Returning the real,
    canonical provider is what makes the per-KB lock meaningful: the upload route
    compares the requested provider against the KB's bound provider, so asking to
    add to a ``pageindex`` KB with ``llamaindex`` (or vice versa) is rejected.
    """
    return normalize_provider_name(raw_provider)


def _assert_provider_ready(provider: str) -> None:
    """Block creating/using a KB whose engine isn't ready.

    PageIndex needs an API key; GraphRAG needs the optional package installed.
    """
    if provider == PAGEINDEX_PROVIDER:
        from deeptutor.services.rag.pipelines.pageindex.config import is_pageindex_configured

        if not is_pageindex_configured():
            raise HTTPException(
                status_code=400,
                detail=(
                    "PageIndex API key is not configured. Add it under "
                    "Knowledge → RAG pipeline settings before creating a PageIndex "
                    "knowledge base."
                ),
            )

    if provider == PAGEINDEX_OSS_PROVIDER:
        from deeptutor.services.rag.preflight import engine_preflight

        report = engine_preflight(provider)
        failed_checks = [
            check
            for check in report.get("checks", [])
            if not check.get("optional") and not check.get("ok")
        ]
        if failed_checks:

View on GitHub (pinned to 3e82f13042)

Solutions

1. Add the PageIndex API key via Knowledge → RAG pipeline settings in the UI
2. Or write it into the active data/user/settings/*.json runtime settings file / process env override
3. Restart/reload the server process so settings are re-read, then retry

Example fix

# before
# no key configured
curl -X POST /api/v1/knowledge -d '{"provider":"pageindex"}'
# after
# settings.json: {"pageindex": {"api_key": "pk-..."}}
curl -X POST /api/v1/knowledge -d '{"provider":"pageindex"}'

from deeptutor.services.rag.pipelines.pageindex.config import is_pageindex_configured
assert is_pageindex_configured(), 'configure PageIndex key first'

When it happens

Trigger: Creating a KB, uploading files, or reindexing with provider=pageindex when the PAGEINDEX_API_KEY (or equivalent settings entry) is missing from data/user/settings/*.json or env overrides.

Common situations: Fresh installs that never configured RAG pipeline settings; key configured in a .env file (which this project ignores by design); key set in a different settings profile than the one the server loaded.

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

• PageIndex OSS preflight failed: {details}
• GraphRAG is not installed. Run `pip install 'deeptutor[graph
• LightRAG is not installed. Run `pip install 'deeptutor[rag-l
• PageIndex knowledge bases accept: {supported}. Unsupported:
• Azure OpenAI api_key is required

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