{"record":{"id":"8bc83cb7488c9a42","repo":"HKUDS/DeepTutor","slug":"result-error-or-could-not-connect-to-the-lightrag","errorCode":null,"errorMessage":"result.error or \"Could not connect to the LightRAG server.\"","messagePattern":"result\\.error or \"Could not connect to the LightRAG server\\.\"","errorType":"http","errorClass":"HTTPException","httpStatus":400,"severity":"error","filePath":"deeptutor/api/routers/knowledge.py","lineNumber":1900,"sourceCode":"@router.post(\"/connect-lightrag-server\")\nasync def connect_lightrag_server_route(payload: ConnectLightRagServerRequest):\n    \"\"\"Connect an external LightRAG server as a retrieval-only knowledge base.\n\n    Re-probes server-side (never trusts the client's verdict), then registers a\n    pointer (``type: lightrag_server``). Retrieval is offloaded to the server's\n    ``/query`` endpoint — no copy, no local index.\n    \"\"\"\n    from deeptutor.services.rag.pipelines.lightrag_server.config import SUPPORTED_MODES\n    from deeptutor.services.rag.pipelines.lightrag_server.probe import probe_server\n\n    name = (payload.name or \"\").strip()\n    server_url = (payload.server_url or \"\").strip()\n    if not name or not server_url:\n        raise HTTPException(status_code=400, detail=\"Both name and server_url are required.\")\n\n    result = await probe_server(server_url, payload.api_key or \"\")\n    if not result.ok:\n        raise HTTPException(\n            status_code=400, detail=result.error or \"Could not connect to the LightRAG server.\"\n        )\n\n    search_mode = (payload.search_mode or \"\").strip().lower()\n    if search_mode and search_mode not in SUPPORTED_MODES:\n        search_mode = \"\"\n\n    try:\n        manager = get_kb_manager()\n        entry = manager.register_lightrag_server_kb(\n            name,\n            result.base_url,\n            api_key=payload.api_key or \"\",\n            search_mode=search_mode,\n        )\n    except ValueError as e:\n        raise HTTPException(status_code=400, detail=str(e))\n    except HTTPException:","sourceCodeStart":1882,"sourceCodeEnd":1918,"githubUrl":"https://github.com/HKUDS/DeepTutor/blob/3e82f130422a813cdd73c10b21a44e9325f5821a/deeptutor/api/routers/knowledge.py#L1882-L1918","documentation":"HTTP 400 raised when probe_server() reports failure (result.ok == false) during a LightRAG connect attempt. The detail is the probe's own error message, falling back to a generic message when the probe didn't record one — i.e. the URL was syntactically acceptable but the server didn't respond as a LightRAG instance.","triggerScenarios":"POST /connect-lightrag-server where the URL is unreachable, returns non-HTTP-200 on health endpoints, TLS errors, wrong port, a non-LightRAG service at that address, or an invalid api_key causing an auth failure during probing.","commonSituations":"LightRAG not started yet, Docker port not published, reverse proxy stripping the health path, or an expired API key.","solutions":["Confirm the LightRAG server is running and reachable (curl the health endpoint from the same host)","Use /probe-lightrag-server first to see the specific probe error before connecting","Fix port/host/TLS or supply the correct api_key and retry","If behind a proxy, verify /health and /webui paths route correctly"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"const probe = await api.probeLightrag(serverUrl, apiKey);\nif (!probe.ok) throw new Error(probe.error);","typeGuard":null,"tryCatchPattern":"try: connect(...) except HTTPException as e: if e.status_code == 400 and 'connect' in e.detail: probe first, fix URL/key, retry","preventionTips":["Always probe before connect","Verify the LightRAG container port is published and health endpoint responds"],"tags":["http-400","lightrag","probe","connection-refused"],"backgroundTag":"service-health-check-failed","analyzedSha":"3e82f130422a813cdd73c10b21a44e9325f5821a","analyzedAt":"2026-08-27T06:57:25.364Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}