{"record":{"id":"afef3e4070c176d5","repo":"unslothai/unsloth","slug":"the-hugging-face-cache-folder-is-invalid","errorCode":null,"errorMessage":"The Hugging Face cache folder is invalid.","messagePattern":"The Hugging Face cache folder is invalid\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"studio/backend/utils/hf_cache_settings.py","lineNumber":252,"sourceCode":"    for directory in (paths.hub_cache, paths.xet_cache):\n        try:\n            directory.mkdir(parents = True, exist_ok = True)\n        except OSError:\n            pass\n    return paths\n\n\ndef _validate_cache_home(raw_path: str) -> Path:\n    value = raw_path.strip()\n    if not value:\n        raise ValueError(\"Choose a cache folder.\")\n    candidate = Path(value).expanduser()\n    if not candidate.is_absolute():\n        raise ValueError(\"The Hugging Face cache folder must be an absolute path.\")\n    try:\n        resolved = candidate.resolve(strict = False)\n    except (OSError, RuntimeError, ValueError) as exc:\n        raise ValueError(\"The Hugging Face cache folder is invalid.\") from exc\n\n    if resolved.parent == resolved:\n        raise ValueError(\"Choose a folder inside the filesystem or drive root.\")\n    try:\n        from hub.storage.scan_folders import (\n            contains_sensitive_path_component,\n            is_denied_system_path,\n        )\n    except ImportError:\n        contains_sensitive_path_component = is_denied_system_path = None\n    if is_denied_system_path is not None and is_denied_system_path(str(resolved)):\n        raise ValueError(\"System folders cannot be used for model downloads.\")\n    if contains_sensitive_path_component is not None and contains_sensitive_path_component(\n        str(resolved)\n    ):\n        raise ValueError(\"Credential or config folders cannot be used for model downloads.\")\n\n    parent = resolved.parent","sourceCodeStart":234,"sourceCodeEnd":270,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/utils/hf_cache_settings.py#L234-L270","documentation":"Raised by _validate_cache_home() in studio/backend/utils/hf_cache_settings.py when Path.resolve(strict=False) throws while canonicalizing the user-supplied Hugging Face cache folder. The three caught causes (OSError, RuntimeError, ValueError) cover symlink loops, name-too-long, embedded NULs, and similar filesystem-level failures that make the path unresolvable. It is a user-facing ValueError, so the Studio UI renders the text directly to the person who typed the path.","triggerScenarios":"Calling set_hf_cache_home() (or any settings route that funnels into _validate_cache_home) with a path that contains a symlink cycle (Path.resolve raises RuntimeError 'Symlink loop'), a path component longer than NAME_MAX (OSError ENAMETOOLONG), or a string with characters that cannot form a valid path (ValueError). The earlier empty/relative-path checks have already passed by the time this fires.","commonSituations":"A user picks a cache folder behind a circular symlink chain, pastes a Windows-style path on Linux (or vice versa) that resolves oddly, or the mountpoint/NAS backing the chosen directory disappears between folder-browse and save. Also seen when a network drive returns I/O errors from the filesystem during path resolution.","solutions":["Pick a plain directory that the OS can stat right now (e.g. under your home directory) and retry saving the setting","If the target is on a network/removable volume, remount it and verify with 'ls <path>' that it is readable before saving","Check for symlink loops with 'readlink -f <path>'; replace the self-referential link with a real directory","If the path was typed by hand, re-select it via the folder picker to eliminate transcription errors"],"exampleFix":"# before: symlink loop\nln -s ~/cache-loop ~/cache-loop\nset_hf_cache_home('~/cache-loop/huggingface')  # ValueError: cache folder is invalid\n\n# after: real directory\nmkdir -p ~/hf-cache\nset_hf_cache_home('~/hf-cache')  # ok","handlingStrategy":"validation","validationCode":"from pathlib import Path\n\ndef cache_home_resolves(raw: str) -> bool:\n    try:\n        Path(raw.strip()).expanduser().resolve(strict=False)\n        return True\n    except (OSError, RuntimeError, ValueError):\n        return False\n\n# run before calling set_hf_cache_home","typeGuard":null,"tryCatchPattern":"try:\n    set_hf_cache_home(path)\nexcept ValueError as exc:\n    show_user(str(exc))  # all _validate_cache_home failures are ValueError with UI-ready text","preventionTips":["Offer a folder picker instead of free-text path entry","Validate resolvability client-side before submit","Avoid pointing the cache at deeply symlinked or network paths you do not control"],"tags":["huggingface","cache","filesystem","validation","path"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}