{"record":{"id":"1f021464711b3f24","repo":"unslothai/unsloth","slug":"studio-cannot-use-this-cache-folder-exc","errorCode":null,"errorMessage":"Studio cannot use this cache folder: {exc}","messagePattern":"Studio cannot use this cache folder: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"studio/backend/utils/hf_cache_settings.py","lineNumber":284,"sourceCode":"        str(resolved)\n    ):\n        raise ValueError(\"Credential or config folders cannot be used for model downloads.\")\n\n    parent = resolved.parent\n    if not parent.exists() or not parent.is_dir():\n        raise ValueError(\"The parent folder does not exist.\")\n    try:\n        resolved.mkdir(exist_ok = True)\n        if not resolved.is_dir():\n            raise ValueError(\"The selected cache location is not a folder.\")\n        for child in (resolved / \"hub\", resolved / \"xet\"):\n            child.mkdir(exist_ok = True)\n            with tempfile.NamedTemporaryFile(prefix = \".unsloth-write-test-\", dir = child):\n                pass\n    except PermissionError as exc:\n        raise ValueError(\"Studio does not have permission to write to this folder.\") from exc\n    except OSError as exc:\n        raise ValueError(f\"Studio cannot use this cache folder: {exc}\") from exc\n    return resolved\n\n\ndef _stored_history() -> list[Path]:\n    try:\n        from storage.studio_db import get_app_setting\n        raw = get_app_setting(CACHE_HISTORY_SETTING_KEY, [])\n    except Exception:\n        raw = []\n    if not isinstance(raw, list):\n        return []\n    out: list[Path] = []\n    seen: set[str] = set()\n    for value in raw:\n        if not isinstance(value, str) or not value.strip():\n            continue\n        try:\n            path = _canonical(value)","sourceCodeStart":266,"sourceCodeEnd":302,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/utils/hf_cache_settings.py#L266-L302","documentation":"Catch-all for any OSError other than PermissionError thrown by the mkdir/probe block; the original exception text is embedded so the user sees the concrete OS failure (disk full, I/O error, quota). It preserves the cause via 'from exc' for debugging while keeping a stable, actionable prefix.","triggerScenarios":"ENOSPC when the volume fills during the write test; EIO/EDQUOT on failing or quota-capped network shares; ENOENT when a path component vanishes mid-probe; a filesystem returning EROFS even though mode bits looked writable. Any OSError from resolved.mkdir, child.mkdir, or the NamedTemporaryFile test lands here.","commonSituations":"A full disk (most common); quota exhaustion on NFS/home directories; flaky USB drives; VMs with full thin-provisioned disks; SMB shares that drop mid-operation.","solutions":["Free up space or raise the quota on the target volume, then retry (df -h <path>)","For network shares, verify connectivity/stability and remount; run fsck on local volumes reporting I/O errors","Move the cache to a healthy local volume with ample free space","Read the embedded exc text — it names the exact syscall failure and target file"],"exampleFix":"# before: disk full\nset_hf_cache_home('/full-disk/hf')\n# ValueError: Studio cannot use this cache folder: [Errno 28] No space left on device\n\n# after\ndf -h /full-disk && rm -rf /full-disk/junk\nset_hf_cache_home('/full-disk/hf')  # ok","handlingStrategy":"try-catch","validationCode":"import shutil\nfrom pathlib import Path\n\ndef has_free_space(raw: str, min_bytes: int = 5 * 1024**3) -> bool:\n    p = Path(raw).expanduser()\n    target = p if p.exists() else (p.parent if p.parent.exists() else Path.cwd())\n    return shutil.disk_usage(target).free >= min_bytes","typeGuard":null,"tryCatchPattern":"try:\n    set_hf_cache_home(path)\nexcept ValueError as exc:\n    # message embeds the OSError text; surface it verbatim for diagnosis\n    report_to_user(str(exc))","preventionTips":["Monitor free space before large model downloads","Surface the embedded OS error text in logs — it names the exact failure"],"tags":["huggingface","cache","disk-full","io-error","filesystem"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}