{"record":{"id":"d3cd543d93293d09","repo":"HKUDS/DeepTutor","slug":"linked-folder-folder-id-not-found","errorCode":null,"errorMessage":"Linked folder '{folder_id}' not found","messagePattern":"Linked folder '(.+?)' not found","errorType":"http","errorClass":"HTTPException","httpStatus":404,"severity":"error","filePath":"deeptutor/api/routers/knowledge.py","lineNumber":3294,"sourceCode":"    Sync files from a linked folder to the knowledge base.\n\n    This scans the linked folder for supported documents and processes\n    any new files that haven't been added yet.\n    \"\"\"\n    try:\n        manager, kb_name, kb_base_dir = _writable_kb(kb_name)\n        kb_entry = _load_kb_entry_or_404(manager, kb_name)\n        _assert_kb_writable_or_409(kb_name, kb_entry)\n        kb_provider = _validate_registered_provider(\n            kb_entry.get(\"rag_provider\") or DEFAULT_PROVIDER\n        )\n\n        # Get linked folders and find the one with matching ID\n        folders = manager.get_linked_folders(kb_name)\n        folder_info = next((f for f in folders if f[\"id\"] == folder_id), None)\n\n        if not folder_info:\n            raise HTTPException(status_code=404, detail=f\"Linked folder '{folder_id}' not found\")\n\n        folder_path = folder_info[\"path\"]\n\n        # Check for changes (new or modified files)\n        changes = manager.detect_folder_changes(kb_name, folder_id)\n        files_to_process = changes[\"new_files\"] + changes[\"modified_files\"]\n\n        if not files_to_process:\n            return {\"message\": \"No new or modified files to sync\", \"files\": [], \"file_count\": 0}\n\n        logger.info(\n            f\"Syncing {len(files_to_process)} files from folder '{folder_path}' to KB '{kb_name}'\"\n        )\n        task_id = _build_unique_task_id(\"kb_upload\", f\"{kb_name}_folder_{folder_id}\")\n        get_task_stream_manager().ensure_task(task_id)\n\n        # NOTE: We DO NOT update sync state here anymore.\n        # It is updated in run_upload_processing_task only after successful processing.","sourceCodeStart":3276,"sourceCodeEnd":3312,"githubUrl":"https://github.com/HKUDS/DeepTutor/blob/3e82f130422a813cdd73c10b21a44e9325f5821a/deeptutor/api/routers/knowledge.py#L3276-L3312","documentation":"HTTP 404 from POST /{kb_name}/sync-folder/{folder_id} when the folder_id does not match any entry in manager.get_linked_folders(kb_name). Sync only works on currently linked folders.","triggerScenarios":"Syncing a folder id that was unlinked, belongs to a different KB, or is malformed; get_linked_folders returns entries whose 'id' field never equals folder_id.","commonSituations":"UI keeps a cached folder list after unlink; id copied from another KB; folder record removed by manual settings edit.","solutions":["GET the linked-folders list for the KB and confirm the id exists","Re-link the folder (POST link-folder) if it should still be synced","Use ids from the fresh list rather than persisted client state"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"linked = client.get(f'/api/v1/knowledge/{kb}/linked-folders').json()\nif not any(f['id'] == folder_id for f in linked):\n    raise UserWarning(f'{folder_id} is not linked; link it before syncing')","typeGuard":null,"tryCatchPattern":"try:\n    client.post(f'/api/v1/knowledge/{kb}/sync-folder/{folder_id}')\nexcept HTTPError as e:\n    if e.response.status_code == 404:\n        relink_folder_if_needed(kb, folder_id)\n    else: raise","preventionTips":["Sync only ids returned by the current linked-folders list","Re-link before syncing if the folder was removed","Avoid persisting folder ids across sessions without revalidation"],"tags":["linked-folders","sync","http-404","knowledge-base"],"backgroundTag":"resource-not-found","analyzedSha":"3e82f130422a813cdd73c10b21a44e9325f5821a","analyzedAt":"2026-08-27T06:57:25.364Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}