unslothai/unsloth · error · ValueError

The Hugging Face cache folder is invalid.

Error message

The Hugging Face cache folder is invalid.

What it means

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.

Source

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

    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)):
        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

View on GitHub (pinned to 203007d190)

Solutions

1. Pick a plain directory that the OS can stat right now (e.g. under your home directory) and retry saving the setting
2. If the target is on a network/removable volume, remount it and verify with 'ls <path>' that it is readable before saving
3. Check for symlink loops with 'readlink -f <path>'; replace the self-referential link with a real directory
4. If the path was typed by hand, re-select it via the folder picker to eliminate transcription errors

Example fix

# before: symlink loop
ln -s ~/cache-loop ~/cache-loop
set_hf_cache_home('~/cache-loop/huggingface')  # ValueError: cache folder is invalid

# after: real directory
mkdir -p ~/hf-cache
set_hf_cache_home('~/hf-cache')  # ok

from pathlib import Path

def cache_home_resolves(raw: str) -> bool:
    try:
        Path(raw.strip()).expanduser().resolve(strict=False)
        return True
    except (OSError, RuntimeError, ValueError):
        return False

# run before calling set_hf_cache_home

try:
    set_hf_cache_home(path)
except ValueError as exc:
    show_user(str(exc))  # all _validate_cache_home failures are ValueError with UI-ready text

When it happens

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

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

Related errors

• Choose a folder inside the filesystem or drive root.
• The parent folder does not exist.
• The selected cache location is not a folder.
• Studio does not have permission to write to this folder.
• Execution artifact path is not a dataset folder.

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