{"record":{"id":"7f3ac99505b5e1c6","repo":"HKUDS/DeepTutor","slug":"graphrag-preflight-failed-failure-details","errorCode":null,"errorMessage":"GraphRAG preflight failed: {failure_details}","messagePattern":"GraphRAG preflight failed: (.+?)","errorType":"http","errorClass":"HTTPException","httpStatus":409,"severity":"error","filePath":"deeptutor/api/routers/knowledge.py","lineNumber":708,"sourceCode":"                    \"`pip install 'deeptutor[graphrag]'` on the server before \"\n                    \"creating a GraphRAG knowledge base.\"\n                ),\n            )\n\n        from deeptutor.services.rag.preflight import engine_preflight\n\n        report = engine_preflight(provider)\n        failed_checks = [\n            check\n            for check in report.get(\"checks\", [])\n            if not check.get(\"optional\") and not check.get(\"ok\")\n        ]\n        if failed_checks:\n            failure_details = \"; \".join(\n                str(check.get(\"detail\") or check.get(\"label\") or \"Requirement not met\")\n                for check in failed_checks\n            )\n            raise HTTPException(\n                status_code=409,\n                detail=f\"GraphRAG preflight failed: {failure_details}\",\n            )\n\n    if provider == LIGHTRAG_PROVIDER:\n        from deeptutor.services.rag.pipelines.lightrag.config import is_lightrag_available\n\n        if not is_lightrag_available():\n            raise HTTPException(\n                status_code=400,\n                detail=(\n                    \"LightRAG is not installed. Run \"\n                    \"`pip install 'deeptutor[rag-lightrag]'` on the server before \"\n                    \"creating a LightRAG knowledge base.\"\n                ),\n            )\n\n","sourceCodeStart":690,"sourceCodeEnd":726,"githubUrl":"https://github.com/HKUDS/DeepTutor/blob/3e82f130422a813cdd73c10b21a44e9325f5821a/deeptutor/api/routers/knowledge.py#L690-L726","documentation":"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.","triggerScenarios":"GraphRAG create/upload/reindex where the preflight list contains failures — typically missing LLM API credentials or embedding configuration required by GraphRAG's indexing pipeline.","commonSituations":"GraphRAG extra installed but no LLM key configured; embeddings endpoint missing; changed model settings after initial setup invalidated the cached preflight.","solutions":["Inspect the joined failure details to see which checks failed","Configure the LLM/embedding settings GraphRAG requires (API keys under RAG pipeline settings)","Use the readiness/status endpoint (no paid model call is made) to confirm all checks pass","Retry the original operation"],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"# query readiness endpoint (explicitly free of paid model calls)\nready = all_providers_ready(client, 'graphrag')\nif not ready: block_ui_action('GraphRAG create')","typeGuard":null,"tryCatchPattern":"try: create_kb(provider='graphrag')\nexcept HTTPError as e:\n    if e.response.status_code == 409: configure_llm_embeddings(); retry()","preventionTips":["Complete LLM/embedding configuration before enabling GraphRAG","Cache readiness state but re-check on config changes"],"tags":["graphrag","rag","preflight","environment","http-409"],"backgroundTag":"preflight-checks-failed","analyzedSha":"3e82f130422a813cdd73c10b21a44e9325f5821a","analyzedAt":"2026-08-27T06:57:25.364Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}