unslothai/unsloth · error · ValueError

The Hugging Face cache folder must be an absolute path.

Error message

The Hugging Face cache folder must be an absolute path.

What it means

Raised by _validate_cache_home when the (non-empty) cache folder value is a relative path. The Hugging Face cache must be pinned to a fixed absolute location so cache resolution stays stable regardless of the process working directory. This check runs after the empty check and before resolve()/sensitive-path checks.

Source

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

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

View on GitHub (pinned to 203007d190)

Solutions

1. Use an absolute path: /home/user/.cache/huggingface or C:\\Users\\me\\hf-cache.
2. If you have a relative path programmatically, absolutize it first: Path(p).expanduser().resolve().
3. In the UI, use a folder picker that returns absolute paths instead of free text.
4. For per-project caches, compute the absolute path from the project root before saving.

Example fix

# before
set_cache_home("hf_cache")  # relative -> ValueError

# after
from pathlib import Path
set_cache_home(str(Path("hf_cache").resolve()))  # /proj/hf_cache

from pathlib import Path

def is_absolute_expanded(raw) -> bool:
    try:
        return Path(str(raw).strip()).expanduser().is_absolute()
    except Exception:
        return False

# guard: assert is_absolute_expanded(raw) before set_cache_home(raw)

def is_absolute_cache_path(value) -> bool:
    if not isinstance(value, str) or not value.strip():
        return False
    return Path(value.strip()).expanduser().is_absolute()

When it happens

Trigger: Passing a relative path like 'hf_cache', './cache/huggingface', or '~' without expansion context (note: expanduser IS applied, so '~/x' is fine, but 'x/y' is not) to the cache-home setter.

Common situations: Users entering a folder name in the settings UI instead of picking a folder; configs written with project-relative paths; porting configs between tools where relative cache dirs are common; cwd-dependent behavior breaking cache hits.

Related errors

• Choose a cache folder.
• Multiple cached {noun} differ only by case. Delete the exact
• Failed to read the local dataset cache.
• Invalid repo_id format
• Failed to create models folder: {path}: {e}

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