HKUDS/DeepTutor · warning · HTTPException

Folder '{folder_id}' not found

Error message

Folder '{folder_id}' not found

What it means

HTTP 404 from DELETE /{kb_name}/linked-folders/{folder_id} when manager.unlink_folder returns falsy — the folder_id is not among the KB's linked folders (already unlinked or never linked).

Source

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

        manager = manager_for_resource(resource)
        folders = manager.get_linked_folders(resource.name)
        return [LinkedFolderInfo(**f) for f in folders]
    except HTTPException:
        raise
    except ValueError:
        raise HTTPException(status_code=404, detail=f"Knowledge base '{kb_name}' not found")
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))


@router.delete("/{kb_name}/linked-folders/{folder_id}")
async def unlink_folder(kb_name: str, folder_id: str):
    """Unlink a folder from a knowledge base."""
    try:
        manager, resolved_name, _ = _writable_kb(kb_name)
        success = manager.unlink_folder(resolved_name, folder_id)
        if not success:
            raise HTTPException(status_code=404, detail=f"Folder '{folder_id}' not found")
        logger.info(f"Unlinked folder '{folder_id}' from KB '{kb_name}'")
        return {"message": "Folder unlinked successfully", "folder_id": folder_id}
    except HTTPException:
        raise
    except ValueError:
        raise HTTPException(status_code=404, detail=f"Knowledge base '{kb_name}' not found")
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))


@router.post("/{kb_name}/sync-folder/{folder_id}")
async def sync_folder(kb_name: str, folder_id: str, background_tasks: BackgroundTasks):
    """
    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.
    """

View on GitHub (pinned to 3e82f13042)

Solutions

  1. Re-fetch the linked folders list and confirm folder_id still appears
  2. Treat 404 on unlink as success if the goal is 'folder not linked' (idempotent delete)
  3. Fix UI to disable the unlink button for folders missing from the fresh list

Example fix

# before
DELETE /kb/my-kb/linked-folders/folder-123  -> 404 Folder 'folder-123' not found
# after (idempotent client)
if resp.status_code == 404:
    pass  # already unlinked
Defensive patterns

Strategy: try-catch

Validate before calling

folder_ids = {f['id'] for f in client.get(f'/api/v1/knowledge/{kb}/linked-folders').json()}
if folder_id not in folder_ids:
    return  # already unlinked

Try / catch

try:
    client.delete(f'/api/v1/knowledge/{kb}/linked-folders/{folder_id}')
except HTTPError as e:
    if e.response.status_code == 404 and 'Folder' in e.response.json()['detail']:
        pass  # idempotent success
    else: raise

Prevention

When it happens

Trigger: DELETE a linked folder with a folder_id that does not exist for that KB, e.g. after it was already unlinked from another tab/session or the id was mistyped.

Common situations: Double-click / duplicate UI action unlinks twice; stale folder list in the UI; folder unlinked by a sync job between listing and deleting.

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/c02ac4f524611da7. Report an issue: GitHub.