unslothai/unsloth · error · ValueError

Studio does not have permission to write to this folder.

Error message

Studio does not have permission to write to this folder.

What it means

Raised when the mkdir/write-probe block (mkdir of the cache dir, mkdir of hub/ and xet/ subfolders, and a NamedTemporaryFile write test inside each) raises PermissionError. It converts the raw OS error into a message the user can act on: the process (Studio backend) lacks write permission on the chosen location.

Source

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

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

View on GitHub (pinned to 203007d190)

Solutions

1. chown the folder to the backend user or chmod it writable: chown -R $(whoami) /data/hf-cache
2. Relocate to a user-writable path such as ~/hf-cache
3. Remount read-only volumes read-write (e.g. fix ntfs mount options, or the Docker volume perms)
4. On macOS, grant the terminal/app Full Disk Access or pick a location outside protected folders

Example fix

# before
set_hf_cache_home('/opt/hf-cache')  # PermissionError -> ValueError

# after
sudo chown -R $USER /opt/hf-cache   # or use a home-dir path
set_hf_cache_home('/opt/hf-cache')  # ok

import os, tempfile
from pathlib import Path

def writable_probe(raw: str) -> bool:
    p = Path(raw).expanduser().resolve(strict=False)
    try:
        p.mkdir(parents=True, exist_ok=True)
        with tempfile.NamedTemporaryFile(dir=p):
            pass
        return True
    except (PermissionError, OSError):
        return False

try:
    set_hf_cache_home(path)
except ValueError as exc:
    if 'permission' in str(exc).lower():
        prompt_fix_permissions(path)
    else:
        raise

When it happens

Trigger: set_hf_cache_home() pointing at a directory owned by another user or root with no write bit for the backend's user; macOS App Sandbox / full-disk-access denial; a read-only mount (exFAT/NTFS mounts, read-only Docker volumes); SELinux/AppArmor denying writes despite mode bits looking fine.

Common situations: Picking /opt or /srv (root-owned) without sudo; a second drive formatted NTFS mounted read-only on Linux; running the backend as a different user than the one that owns the external drive; corporate endpoint protection blocking writes.

Related errors

• The Hugging Face cache folder is invalid.
• The parent folder does not exist.
• The selected cache location is not a folder.
• Execution artifact path is not a dataset folder.
• Path is not readable

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