{"record":{"id":"71929462cc8c4b4d","repo":"HKUDS/DeepTutor","slug":"result-error-or-folder-is-not-linkable","errorCode":null,"errorMessage":"result.error or \"Folder is not linkable.\"","messagePattern":"result\\.error or \"Folder is not linkable\\.\"","errorType":"http","errorClass":"HTTPException","httpStatus":400,"severity":"error","filePath":"deeptutor/api/routers/knowledge.py","lineNumber":1823,"sourceCode":"    \"\"\"Mount an existing engine index as a read-only ``linked`` knowledge base.\n\n    Re-probes server-side (never trusts the client's verdict), then registers a\n    pointer to the folder. Retrieval reads the index in place — no copy, no\n    re-index. Embedding-mismatch warnings do not block the link (the user may\n    switch embedding models later); a missing/invalid index does.\n    \"\"\"\n    name = (payload.name or \"\").strip()\n    folder_path = (payload.folder_path or \"\").strip()\n    if not name or not folder_path:\n        raise HTTPException(status_code=400, detail=\"Both name and folder_path are required.\")\n    try:\n        folder = assert_path_allowed(folder_path)\n    except ValueError as e:\n        raise HTTPException(status_code=400, detail=str(e))\n\n    result = probe_linked_folder(str(folder), payload.rag_provider)\n    if not result.ok:\n        raise HTTPException(status_code=400, detail=result.error or \"Folder is not linkable.\")\n\n    stats = {\n        \"embedding_model\": result.embedding.index_model,\n        \"doc_count\": result.doc_count,\n    }\n    try:\n        manager = get_kb_manager()\n        entry = manager.register_linked_kb(\n            name,\n            str(folder),\n            result.provider,\n            stats=stats,\n        )\n    except ValueError as e:\n        raise HTTPException(status_code=400, detail=str(e))\n    except HTTPException:\n        raise\n    except Exception as e:","sourceCodeStart":1805,"sourceCodeEnd":1841,"githubUrl":"https://github.com/HKUDS/DeepTutor/blob/3e82f130422a813cdd73c10b21a44e9325f5821a/deeptutor/api/routers/knowledge.py#L1805-L1841","documentation":"Link refusal in POST /connect-folder: the server-side re-probe of the folder (which never trusts the client's earlier probe verdict) returned an error verdict, meaning the folder has a missing or invalid engine index and is not linkable. The 400 detail is result.error when present, falling back to the generic 'Folder is not linkable.' Embedding-mismatch warnings do not trigger this — only a hard probe error does.","triggerScenarios":"Thrown at deeptutor/api/routers/knowledge.py:1823 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Inspect the detail/result.error for the specific probe verdict","Ensure the folder actually contains a ready, valid engine index before linking","Re-run POST /probe-folder to preview the verdict without registering"],"exampleFix":null,"handlingStrategy":"validation","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"3e82f130422a813cdd73c10b21a44e9325f5821a","analyzedAt":"2026-08-27T06:57:25.364Z","contentChangedAt":"2026-08-27T06:57:25.364Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}