HKUDS/DeepTutor · error · HTTPException

result.error or "Could not connect to the LightRAG server."

Error message

result.error or "Could not connect to the LightRAG server."

What it means

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.

Source

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

@router.post("/connect-lightrag-server")
async def connect_lightrag_server_route(payload: ConnectLightRagServerRequest):
    """Connect an external LightRAG server as a retrieval-only knowledge base.

    Re-probes server-side (never trusts the client's verdict), then registers a
    pointer (``type: lightrag_server``). Retrieval is offloaded to the server's
    ``/query`` endpoint — no copy, no local index.
    """
    from deeptutor.services.rag.pipelines.lightrag_server.config import SUPPORTED_MODES
    from deeptutor.services.rag.pipelines.lightrag_server.probe import probe_server

    name = (payload.name or "").strip()
    server_url = (payload.server_url or "").strip()
    if not name or not server_url:
        raise HTTPException(status_code=400, detail="Both name and server_url are required.")

    result = await probe_server(server_url, payload.api_key or "")
    if not result.ok:
        raise HTTPException(
            status_code=400, detail=result.error or "Could not connect to the LightRAG server."
        )

    search_mode = (payload.search_mode or "").strip().lower()
    if search_mode and search_mode not in SUPPORTED_MODES:
        search_mode = ""

    try:
        manager = get_kb_manager()
        entry = manager.register_lightrag_server_kb(
            name,
            result.base_url,
            api_key=payload.api_key or "",
            search_mode=search_mode,
        )
    except ValueError as e:
        raise HTTPException(status_code=400, detail=str(e))
    except HTTPException:

View on GitHub (pinned to 3e82f13042)

Solutions

1. Confirm the LightRAG server is running and reachable (curl the health endpoint from the same host)
2. Use /probe-lightrag-server first to see the specific probe error before connecting
3. Fix port/host/TLS or supply the correct api_key and retry
4. If behind a proxy, verify /health and /webui paths route correctly

const probe = await api.probeLightrag(serverUrl, apiKey);
if (!probe.ok) throw new Error(probe.error);

try: connect(...) except HTTPException as e: if e.status_code == 400 and 'connect' in e.detail: probe first, fix URL/key, retry

When it happens

Trigger: 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.

Common situations: LightRAG not started yet, Docker port not published, reverse proxy stripping the health path, or an expired API key.

Related errors

• LightRAG is not installed. Run `pip install 'deeptutor[rag-l
• server_url is required.
• Both name and server_url are required.
• No sessions to import
• Archive '{sanitized_filename}' exceeds maximum size limit of

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