{"record":{"id":"43dbe1d0a9c6abc1","repo":"HKUDS/DeepTutor","slug":"pageindex-oss-preflight-failed-details","errorCode":null,"errorMessage":"PageIndex OSS preflight failed: {details}","messagePattern":"PageIndex OSS preflight failed: (.+?)","errorType":"http","errorClass":"HTTPException","httpStatus":409,"severity":"error","filePath":"deeptutor/api/routers/knowledge.py","lineNumber":678,"sourceCode":"                    \"knowledge base.\"\n                ),\n            )\n\n    if provider == PAGEINDEX_OSS_PROVIDER:\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            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, detail=f\"PageIndex OSS preflight failed: {details}\"\n            )\n\n    if provider == GRAPHRAG_PROVIDER:\n        from deeptutor.services.rag.pipelines.graphrag.config import is_graphrag_available\n\n        if not is_graphrag_available():\n            raise HTTPException(\n                status_code=400,\n                detail=(\n                    \"GraphRAG is not installed. Run \"\n                    \"`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","sourceCodeStart":660,"sourceCodeEnd":696,"githubUrl":"https://github.com/HKUDS/DeepTutor/blob/3e82f130422a813cdd73c10b21a44e9325f5821a/deeptutor/api/routers/knowledge.py#L660-L696","documentation":"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.","triggerScenarios":"Provider preflight during create/upload/reindex for PageIndex OSS when any environment requirement check fails — missing local runtime, unmet resource requirements, or incomplete setup.","commonSituations":"Self-hosted PageIndex OSS installed partially; server resource limits (disk/memory) below requirements; version drift between the deeptutor integration and the local PageIndex runtime.","solutions":["Read the joined details — each failed check's detail/label names the specific unmet requirement","Complete the PageIndex OSS setup step that failed (install runtime/models as its docs describe)","Free up or increase the resource (disk/memory) the check complains about","Re-run the provider readiness/status endpoint (it does not make paid model calls) until checks pass, then retry"],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"resp = client.get('/api/v1/knowledge/rag/providers')  # readiness, no paid calls\nfailed = [p for p in resp['providers'] if p['id']=='pageindex' and not p['ready']]\nassert not failed, failed","typeGuard":null,"tryCatchPattern":"try: create_kb(provider='pageindex')\nexcept HTTPError as e:\n    if e.response.status_code == 409 and 'preflight failed' in e.response.text():\n        fix_environment_then_retry()","preventionTips":["Surface preflight results in the UI before KB creation","Automate PageIndex OSS setup checks in deployment scripts"],"tags":["pageindex","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"}