{"record":{"id":"df57b38f2a1993d1","repo":"unslothai/unsloth","slug":"failed-to-read-the-local-dataset-cache","errorCode":null,"errorMessage":"Failed to read the local dataset cache.","messagePattern":"Failed to read the local dataset cache\\.","errorType":"http","errorClass":"HTTPException","httpStatus":500,"severity":"error","filePath":"studio/backend/hub/services/datasets/cache_inventory.py","lineNumber":531,"sourceCode":"            )\n            existing[\"processed_cache\"] = True\n            existing[\"app_processed_cache\"] = True\n    logger.info(\n        \"Cached dataset scan: roots=%d inspected=%d returned=%d\",\n        len(seen_roots) or len(scans),\n        inspected,\n        len(seen_lower),\n    )\n    return sorted(seen_lower.values(), key = lambda c: c[\"repo_id\"])\n\n\nasync def list_cached_datasets_response() -> dict:\n    \"\"\"List dataset repos already downloaded into the HF cache.\"\"\"\n    try:\n        return {\"cached\": await asyncio.to_thread(_scan_hf_dataset_caches)}\n    except Exception as exc:\n        logger.error(\"Error listing cached datasets: %s\", exc, exc_info = True)\n        raise HTTPException(\n            status_code = 500,\n            detail = \"Failed to read the local dataset cache.\",\n        ) from exc\n\n\nasync def delete_cached_dataset_response(repo_id: str, cache_path: Optional[str] = None) -> dict:\n    \"\"\"Remove a cached dataset repo from the HF cache.\"\"\"\n    if not _is_valid_repo_id(repo_id):\n        raise HTTPException(status_code = 400, detail = \"Invalid repo_id format\")\n\n    repo_key = await asyncio.to_thread(resolve_cached_repo_id_case, repo_id, repo_type = \"dataset\")\n    if not downloads.registry.begin_delete(repo_key):\n        raise HTTPException(\n            status_code = 400,\n            detail = \"Cancel the active download before deleting.\",\n        )\n    try:\n        return await asyncio.to_thread(_delete_cached_dataset_blocking, repo_key, cache_path)","sourceCodeStart":513,"sourceCodeEnd":549,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/hub/services/datasets/cache_inventory.py#L513-L549","documentation":"HTTPException 500 raised by list_cached_datasets_response when the background scan of the local HF dataset caches (_scan_hf_dataset_caches, run via asyncio.to_thread) raises any exception. The original error is logged with a traceback before being wrapped, so the server log holds the root cause (permissions, unexpected dir layout, disk errors).","triggerScenarios":"Any unexpected exception while walking HF cache directories: unreadable/permission-denied paths, malformed snapshot dirs, OSError from a disconnected mount, or a bug in the scan logic for an unforeseen cache layout.","commonSituations":"Cache dir owned by another user or with restrictive perms; NFS/external drive unmounted mid-scan; cache written by a newer/older huggingface_hub layout; partial/interrupted downloads leaving odd structures.","solutions":["Read the server log for the 'Error listing cached datasets' entry — the traceback names the real cause.","Fix filesystem-level issues: restore read permissions on the HF cache, remount the volume, remove corrupted repo dirs.","If the cache layout is incompatible, move ~/.cache/huggingface aside and let it rebuild (re-download as needed)."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"from pathlib import Path\n\ndef hf_cache_readable(cache_dir: Path) -> bool:\n    try:\n        for d in cache_dir.rglob(\"*\"):\n            if d.is_dir() and not d.stat().st_mode & 0o004:\n                return False\n        return True\n    except OSError:\n        return False","typeGuard":null,"tryCatchPattern":"import httpx\n\nresp = httpx.get(f\"{api}/hub/datasets/cached\")\nif resp.status_code == 500 and \"Failed to read the local dataset cache\" in resp.text:\n    check_server_logs_and_cache_permissions()  # then surface a retry to the user","preventionTips":["Keep HF cache directories readable by the backend service user.","Avoid moving/remounting cache volumes while the app runs.","On persistent 500s, check server logs first — the traceback names the real cause."],"tags":["hf-cache","datasets","filesystem","http-500"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}