{"record":{"id":"bf053915e9158d55","repo":"unslothai/unsloth","slug":"system-folders-cannot-be-used-for-model-downloads","errorCode":null,"errorMessage":"System folders cannot be used for model downloads.","messagePattern":"System folders cannot be used for model downloads\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"studio/backend/utils/hf_cache_settings.py","lineNumber":264,"sourceCode":"    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\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","sourceCodeStart":246,"sourceCodeEnd":282,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/utils/hf_cache_settings.py#L246-L282","documentation":"Raised when is_denied_system_path() from hub.storage.scan_folders classifies the resolved cache folder as a protected OS location (e.g. /bin, /usr, /System, C:\\Windows). The blocklist prevents model downloads from being written into directories the OS owns, which could corrupt system files or fail mid-download due to permissions.","triggerScenarios":"set_hf_cache_home() with a path that resolves into a system directory: '/usr/local/hf', '/bin/cache', 'C:\\Windows\\Temp\\hf', or a symlink that resolves into one. The scan_folders import must have succeeded (otherwise the check is silently skipped with both helpers set to None), and the resolved path must match the denied-path list.","commonSituations":"Users trying to put the cache 'somewhere always writable' pick /tmp variants that are on the denied list, or point at /usr/... out of habit from system-wide installs. Containers where /usr is the only large volume also trigger it.","solutions":["Use a user-owned location like ~/.cache/huggingface or /home/<user>/hf-cache","Check what scan_folders considers denied (import hub.storage.scan_folders; inspect its path list) if you believe the path is safe","For Docker containers, mount a dedicated volume at a non-system path (e.g. /data/hf) and use that"],"exampleFix":"# before\nset_hf_cache_home('/usr/share/hf-cache')  # ValueError: system folders\n\n# after\nset_hf_cache_home('/home/me/hf-cache')   # ok","handlingStrategy":"validation","validationCode":"from hub.storage.scan_folders import is_denied_system_path\n\ndef safe_cache_choice(raw: str) -> bool:\n    return not is_denied_system_path(str(Path(raw).expanduser().resolve(strict=False)))","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Prefer user-home locations for caches","Reuse the same scan_folders predicates the backend uses so client and server agree","Warn when a picked path resolves into /usr, /bin, C:\\Windows, or similar"],"tags":["huggingface","cache","system-paths","security","validation"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}