unslothai/unsloth · error · ValueError

Choose a folder inside the filesystem or drive root.

Error message

Choose a folder inside the filesystem or drive root.

What it means

Raised when the resolved cache folder equals its own parent (resolved.parent == resolved), which is only true for a filesystem root such as '/', 'C:\', or a UNC drive root. The guard exists because using a drive root as a cache home would scatter hub/xet directories and temp files across the root of the volume and break per-volume tooling assumptions.

Source

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

        except OSError:
            pass
    return paths


def _validate_cache_home(raw_path: str) -> Path:
    value = raw_path.strip()
    if not value:
        raise ValueError("Choose a cache folder.")
    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:

View on GitHub (pinned to 203007d190)

Solutions

1. Choose a named subfolder, e.g. '/mnt/data/huggingface' or 'D:\hf-cache', instead of the drive root
2. Create the folder first (mkdir) and select it from the folder picker rather than typing the root
3. If you genuinely want the volume root, accept the restriction and use a one-level-deep directory

Example fix

# before
set_hf_cache_home('/')            # ValueError: choose a folder inside the root

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

from pathlib import Path

def is_root_path(raw: str) -> bool:
    p = Path(raw).expanduser().resolve(strict=False)
    return p.parent == p

if is_root_path(user_path): reject with 'pick a subfolder'

When it happens

Trigger: set_hf_cache_home('/') on Linux/macOS, set_hf_cache_home('C:\') or 'D:/' on Windows, or any path that resolves to a drive/filesystem root. It fires after successful resolve() but before the sensitive-path and writability checks, so the root case is rejected first.

Common situations: A user tries to give the app the whole drive to 'avoid permission problems', or types the mount point of a freshly mounted data disk (e.g. '/mnt/data' is fine, but '/' or a path resolving to a mount root is not). Windows users pasting 'D:' without a subfolder are the classic case.

Related errors

• The Hugging Face cache folder is invalid.
• System folders cannot be used for model downloads.
• Credential or config folders cannot be used for model downlo
• The parent folder does not exist.
• The selected cache location is not a folder.

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