unslothai/unsloth · error · ValueError

Studio cannot use this cache folder: {exc}

Error message

Studio cannot use this cache folder: {exc}

What it means

Catch-all for any OSError other than PermissionError thrown by the mkdir/probe block; the original exception text is embedded so the user sees the concrete OS failure (disk full, I/O error, quota). It preserves the cause via 'from exc' for debugging while keeping a stable, actionable prefix.

Source

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

        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
    except OSError as exc:
        raise ValueError(f"Studio cannot use this cache folder: {exc}") from exc
    return resolved


def _stored_history() -> list[Path]:
    try:
        from storage.studio_db import get_app_setting
        raw = get_app_setting(CACHE_HISTORY_SETTING_KEY, [])
    except Exception:
        raw = []
    if not isinstance(raw, list):
        return []
    out: list[Path] = []
    seen: set[str] = set()
    for value in raw:
        if not isinstance(value, str) or not value.strip():
            continue
        try:
            path = _canonical(value)

View on GitHub (pinned to 203007d190)

Solutions

1. Free up space or raise the quota on the target volume, then retry (df -h <path>)
2. For network shares, verify connectivity/stability and remount; run fsck on local volumes reporting I/O errors
3. Move the cache to a healthy local volume with ample free space
4. Read the embedded exc text — it names the exact syscall failure and target file

Example fix

# before: disk full
set_hf_cache_home('/full-disk/hf')
# ValueError: Studio cannot use this cache folder: [Errno 28] No space left on device

# after
df -h /full-disk && rm -rf /full-disk/junk
set_hf_cache_home('/full-disk/hf')  # ok

import shutil
from pathlib import Path

def has_free_space(raw: str, min_bytes: int = 5 * 1024**3) -> bool:
    p = Path(raw).expanduser()
    target = p if p.exists() else (p.parent if p.parent.exists() else Path.cwd())
    return shutil.disk_usage(target).free >= min_bytes

try:
    set_hf_cache_home(path)
except ValueError as exc:
    # message embeds the OSError text; surface it verbatim for diagnosis
    report_to_user(str(exc))

When it happens

Trigger: ENOSPC when the volume fills during the write test; EIO/EDQUOT on failing or quota-capped network shares; ENOENT when a path component vanishes mid-probe; a filesystem returning EROFS even though mode bits looked writable. Any OSError from resolved.mkdir, child.mkdir, or the NamedTemporaryFile test lands here.

Common situations: A full disk (most common); quota exhaustion on NFS/home directories; flaky USB drives; VMs with full thin-provisioned disks; SMB shares that drop mid-operation.

Related errors

• The Hugging Face cache folder is invalid.
• 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 artifacts are no longer available.

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