unslothai/unsloth · error · ValueError

System folders cannot be used for model downloads.

Error message

System folders cannot be used for model downloads.

What it means

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.

Source

Thrown at studio/backend/utils/hf_cache_settings.py:264

    candidate = Path(value).expanduser()
    if not candidate.is_absolute():
        raise ValueError("The Hugging Face cache folder must be an absolute path.")
    try:
        resolved = candidate.resolve(strict = False)
    except (OSError, RuntimeError, ValueError) as exc:
        raise ValueError("The Hugging Face cache folder is invalid.") from exc

    if resolved.parent == resolved:
        raise ValueError("Choose a folder inside the filesystem or drive root.")
    try:
        from hub.storage.scan_folders import (
            contains_sensitive_path_component,
            is_denied_system_path,
        )
    except ImportError:
        contains_sensitive_path_component = is_denied_system_path = None
    if is_denied_system_path is not None and is_denied_system_path(str(resolved)):
        raise ValueError("System folders cannot be used for model downloads.")
    if contains_sensitive_path_component is not None and contains_sensitive_path_component(
        str(resolved)
    ):
        raise ValueError("Credential or config folders cannot be used for model downloads.")

    parent = resolved.parent
    if not parent.exists() or not parent.is_dir():
        raise ValueError("The parent folder does not exist.")
    try:
        resolved.mkdir(exist_ok = True)
        if not resolved.is_dir():
            raise ValueError("The selected cache location is not a folder.")
        for child in (resolved / "hub", resolved / "xet"):
            child.mkdir(exist_ok = True)
            with tempfile.NamedTemporaryFile(prefix = ".unsloth-write-test-", dir = child):
                pass
    except PermissionError as exc:
        raise ValueError("Studio does not have permission to write to this folder.") from exc

View on GitHub (pinned to 203007d190)

Solutions

1. Use a user-owned location like ~/.cache/huggingface or /home/<user>/hf-cache
2. Check what scan_folders considers denied (import hub.storage.scan_folders; inspect its path list) if you believe the path is safe
3. For Docker containers, mount a dedicated volume at a non-system path (e.g. /data/hf) and use that

Example fix

# before
set_hf_cache_home('/usr/share/hf-cache')  # ValueError: system folders

# after
set_hf_cache_home('/home/me/hf-cache')   # ok

from hub.storage.scan_folders import is_denied_system_path

def safe_cache_choice(raw: str) -> bool:
    return not is_denied_system_path(str(Path(raw).expanduser().resolve(strict=False)))

When it happens

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

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

Related errors

• Credential or config folders cannot be used for model downlo
• {_cn_fs.reason}
• Non-GGUF video loads are limited to unsloth/* repos, the off
• The Hugging Face cache folder is invalid.
• Choose a folder inside the filesystem or drive root.

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