unslothai/unsloth · error · ValueError

Choose a cache folder.

Error message

Choose a cache folder.

What it means

Raised by _validate_cache_home when the configured Hugging Face cache folder string is empty after stripping. This is the first, most basic guard in a chain (empty → absolute → resolvable → not filesystem root → not a sensitive/denied system path). The short message reflects a UI-style prompt ('Choose a cache folder.') because the value is typically set from a settings form.

Source

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

    # default while routing cache bytes through the selected home.
    if not os.environ.get("HF_HOME", "").strip():
        os.environ["HF_HOME"] = str(_default_cache_home())
    os.environ["HF_HUB_CACHE"] = str(paths.hub_cache)
    os.environ["HF_XET_CACHE"] = str(paths.xet_cache)
    if "HUGGINGFACE_HUB_CACHE" not in _EXPLICIT_CACHE_ENV:
        os.environ.pop("HUGGINGFACE_HUB_CACHE", None)
    for directory in (paths.hub_cache, paths.xet_cache):
        try:
            directory.mkdir(parents = True, exist_ok = True)
        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)):

View on GitHub (pinned to 203007d190)

Solutions

1. Provide a real absolute path such as /home/user/.cache/huggingface or D:\\hf-cache.
2. To unset/reset, use the dedicated reset path (or remove the setting) rather than saving an empty string.
3. Trim the input client-side and treat blank as 'no change'.
4. If set via env/config file, delete the blank key entirely.

Example fix

# before
set_cache_home("   ")  # ValueError: Choose a cache folder.

# after
set_cache_home("/mnt/data/hf-cache")

def is_nonblank_path(raw) -> bool:
    return isinstance(raw, str) and bool(raw.strip())

def is_settable_cache_home(value) -> bool:
    """Non-blank string; further checks (absolute, safe) happen server-side."""
    return isinstance(value, str) and len(value.strip()) > 0

When it happens

Trigger: Calling the cache-home setter/API with '', ' ', or a value that strips to empty — e.g. a form submitted with the field cleared, or a config key present but blank.

Common situations: User clears the cache-folder field in settings to 'unset' it (the API expects omission, not blank); YAML/JSON config with cache_home: ""; trailing whitespace-only values pasted from a form.

Related errors

• The Hugging Face cache folder must be an absolute path.
• Embedding model must be a Hugging Face repo id (e.g. 'unslot
• Helper LLM startup pre-cache must be true or false.
• Unknown audio_type: {audio_type}
• Unsloth: distributed MLX inference requires parallel_mode='p

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