HKUDS/DeepTutor · error · HTTPException

GraphRAG preflight failed: {failure_details}

Error message

GraphRAG preflight failed: {failure_details}

What it means

Raised by _assert_provider_ready when GraphRAG is installed but its environment preflight (LLM/embedding config, workdir, resources) reports failed checks. The details string joins each failed check's detail/label. HTTP 409 signals the server-side environment is not ready rather than a bad request.

Source

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

                    "`pip install 'deeptutor[graphrag]'` on the server before "
                    "creating a GraphRAG knowledge base."
                ),
            )

        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:
            failure_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"GraphRAG preflight failed: {failure_details}",
            )

    if provider == LIGHTRAG_PROVIDER:
        from deeptutor.services.rag.pipelines.lightrag.config import is_lightrag_available

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

View on GitHub (pinned to 3e82f13042)

Solutions

1. Inspect the joined failure details to see which checks failed
2. Configure the LLM/embedding settings GraphRAG requires (API keys under RAG pipeline settings)
3. Use the readiness/status endpoint (no paid model call is made) to confirm all checks pass
4. Retry the original operation

# query readiness endpoint (explicitly free of paid model calls)
ready = all_providers_ready(client, 'graphrag')
if not ready: block_ui_action('GraphRAG create')

try: create_kb(provider='graphrag')
except HTTPError as e:
    if e.response.status_code == 409: configure_llm_embeddings(); retry()

When it happens

Trigger: GraphRAG create/upload/reindex where the preflight list contains failures — typically missing LLM API credentials or embedding configuration required by GraphRAG's indexing pipeline.

Common situations: GraphRAG extra installed but no LLM key configured; embeddings endpoint missing; changed model settings after initial setup invalidated the cached preflight.

Related errors

• PageIndex OSS preflight failed: {details}
• GraphRAG is not installed. Run `pip install 'deeptutor[graph
• No embedding model is configured. Set up the embedding profi
• Knowledge base '{resolved_name}' is not in an error state. U
• graphrag_model_incompatible

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