HKUDS/DeepTutor · error · HTTPException

Linked folder '{folder_id}' not found

Error message

Linked folder '{folder_id}' not found

What it means

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.

Source

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

    Sync files from a linked folder to the knowledge base.

    This scans the linked folder for supported documents and processes
    any new files that haven't been added yet.
    """
    try:
        manager, kb_name, kb_base_dir = _writable_kb(kb_name)
        kb_entry = _load_kb_entry_or_404(manager, kb_name)
        _assert_kb_writable_or_409(kb_name, kb_entry)
        kb_provider = _validate_registered_provider(
            kb_entry.get("rag_provider") or DEFAULT_PROVIDER
        )

        # Get linked folders and find the one with matching ID
        folders = manager.get_linked_folders(kb_name)
        folder_info = next((f for f in folders if f["id"] == folder_id), None)

        if not folder_info:
            raise HTTPException(status_code=404, detail=f"Linked folder '{folder_id}' not found")

        folder_path = folder_info["path"]

        # Check for changes (new or modified files)
        changes = manager.detect_folder_changes(kb_name, folder_id)
        files_to_process = changes["new_files"] + changes["modified_files"]

        if not files_to_process:
            return {"message": "No new or modified files to sync", "files": [], "file_count": 0}

        logger.info(
            f"Syncing {len(files_to_process)} files from folder '{folder_path}' to KB '{kb_name}'"
        )
        task_id = _build_unique_task_id("kb_upload", f"{kb_name}_folder_{folder_id}")
        get_task_stream_manager().ensure_task(task_id)

        # NOTE: We DO NOT update sync state here anymore.
        # It is updated in run_upload_processing_task only after successful processing.

View on GitHub (pinned to 3e82f13042)

Solutions

  1. GET the linked-folders list for the KB and confirm the id exists
  2. Re-link the folder (POST link-folder) if it should still be synced
  3. Use ids from the fresh list rather than persisted client state
Defensive patterns

Strategy: validation

Validate before calling

linked = client.get(f'/api/v1/knowledge/{kb}/linked-folders').json()
if not any(f['id'] == folder_id for f in linked):
    raise UserWarning(f'{folder_id} is not linked; link it before syncing')

Try / catch

try:
    client.post(f'/api/v1/knowledge/{kb}/sync-folder/{folder_id}')
except HTTPError as e:
    if e.response.status_code == 404:
        relink_folder_if_needed(kb, folder_id)
    else: raise

Prevention

When it happens

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

Common situations: UI keeps a cached folder list after unlink; id copied from another KB; folder record removed by manual settings edit.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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