HKUDS/DeepTutor · error · HTTPException

PageIndex OSS preflight failed: {details}

Error message

PageIndex OSS preflight failed: {details}

What it means

Raised by _assert_provider_ready when the PageIndex OSS preflight check-list reports one or more failed checks (missing binary, model weights, disk requirement, etc.). Unlike a missing key (400), this is a 409: the environment is configured but not ready.

Source

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

                    "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:
            details = "; ".join(
                str(check.get("detail") or check.get("label") or "Requirement not met")
                for check in failed_checks
            )
            raise HTTPException(
                status_code=409, detail=f"PageIndex OSS preflight failed: {details}"
            )

    if provider == GRAPHRAG_PROVIDER:
        from deeptutor.services.rag.pipelines.graphrag.config import is_graphrag_available

        if not is_graphrag_available():
            raise HTTPException(
                status_code=400,
                detail=(
                    "GraphRAG is not installed. Run "
                    "`pip install 'deeptutor[graphrag]'` on the server before "
                    "creating a GraphRAG knowledge base."
                ),
            )

        from deeptutor.services.rag.preflight import engine_preflight

View on GitHub (pinned to 3e82f13042)

Solutions

1. Read the joined details — each failed check's detail/label names the specific unmet requirement
2. Complete the PageIndex OSS setup step that failed (install runtime/models as its docs describe)
3. Free up or increase the resource (disk/memory) the check complains about
4. Re-run the provider readiness/status endpoint (it does not make paid model calls) until checks pass, then retry

resp = client.get('/api/v1/knowledge/rag/providers')  # readiness, no paid calls
failed = [p for p in resp['providers'] if p['id']=='pageindex' and not p['ready']]
assert not failed, failed

try: create_kb(provider='pageindex')
except HTTPError as e:
    if e.response.status_code == 409 and 'preflight failed' in e.response.text():
        fix_environment_then_retry()

When it happens

Trigger: Provider preflight during create/upload/reindex for PageIndex OSS when any environment requirement check fails — missing local runtime, unmet resource requirements, or incomplete setup.

Common situations: Self-hosted PageIndex OSS installed partially; server resource limits (disk/memory) below requirements; version drift between the deeptutor integration and the local PageIndex runtime.

Related errors

• GraphRAG preflight failed: {failure_details}
• PageIndex API key is not configured. Add it under Knowledge
• No embedding model is configured. Set up the embedding profi
• Knowledge base '{resolved_name}' is not in an error state. U
• Select at most one PageIndex OSS knowledge base per request.

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