unslothai/unsloth · error · HTTPException

Failed to read the local dataset cache.

Error message

Failed to read the local dataset cache.

What it means

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).

Source

Thrown at studio/backend/hub/services/datasets/cache_inventory.py:531

            )
            existing["processed_cache"] = True
            existing["app_processed_cache"] = True
    logger.info(
        "Cached dataset scan: roots=%d inspected=%d returned=%d",
        len(seen_roots) or len(scans),
        inspected,
        len(seen_lower),
    )
    return sorted(seen_lower.values(), key = lambda c: c["repo_id"])


async def list_cached_datasets_response() -> dict:
    """List dataset repos already downloaded into the HF cache."""
    try:
        return {"cached": await asyncio.to_thread(_scan_hf_dataset_caches)}
    except Exception as exc:
        logger.error("Error listing cached datasets: %s", exc, exc_info = True)
        raise HTTPException(
            status_code = 500,
            detail = "Failed to read the local dataset cache.",
        ) from exc


async def delete_cached_dataset_response(repo_id: str, cache_path: Optional[str] = None) -> dict:
    """Remove a cached dataset repo from the HF cache."""
    if not _is_valid_repo_id(repo_id):
        raise HTTPException(status_code = 400, detail = "Invalid repo_id format")

    repo_key = await asyncio.to_thread(resolve_cached_repo_id_case, repo_id, repo_type = "dataset")
    if not downloads.registry.begin_delete(repo_key):
        raise HTTPException(
            status_code = 400,
            detail = "Cancel the active download before deleting.",
        )
    try:
        return await asyncio.to_thread(_delete_cached_dataset_blocking, repo_key, cache_path)

View on GitHub (pinned to 203007d190)

Solutions

1. Read the server log for the 'Error listing cached datasets' entry — the traceback names the real cause.
2. Fix filesystem-level issues: restore read permissions on the HF cache, remount the volume, remove corrupted repo dirs.
3. If the cache layout is incompatible, move ~/.cache/huggingface aside and let it rebuild (re-download as needed).

from pathlib import Path

def hf_cache_readable(cache_dir: Path) -> bool:
    try:
        for d in cache_dir.rglob("*"):
            if d.is_dir() and not d.stat().st_mode & 0o004:
                return False
        return True
    except OSError:
        return False

import httpx

resp = httpx.get(f"{api}/hub/datasets/cached")
if resp.status_code == 500 and "Failed to read the local dataset cache" in resp.text:
    check_server_logs_and_cache_permissions()  # then surface a retry to the user

When it happens

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

Common situations: 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.

Related errors

• Failed to create models folder: {path}: {e}
• Models folder path is not a directory: {path}
• Invalid repo_id format
• Failed to delete dataset from {len(failures)} cache location
• failed to delete uploaded files

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/df57b38f2a1993d1. Report an issue: GitHub.