HKUDS/DeepTutor · warning · HTTPException

Folder ' ' not found

Error message

Folder '{folder_id}' not found

What it means

Not-found guard (404) in DELETE /{kb_name}/linked-folders/{folder_id}: no linked folder with the given folder_id is registered on this knowledge base. The lookup over manager.get_linked_folders() found no matching id, so there is nothing to unlink.

Solutions

  1. List the KB's linked folders (GET /{kb_name}/linked-folders) to obtain a valid folder_id
  2. Retry with the correct id if the folder was already unlinked

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.

Appendix: 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)