unslothai/unsloth · error · HTTPException

Failed to create models folder: {path}: {e}

Error message

Failed to create models folder: {path}: {e}

What it means

HTTP 500 raised when pre-creating the models folder (the HF hub cache dir resolved from HF_HOME/HF_HUB_CACHE or the default) fails with OSError via Path.mkdir(parents=True, exist_ok=True). Typical OSErrors: permission denied on a parent, read-only filesystem, disk full (ENOSPC), or a non-directory component in the path.

Source

Thrown at studio/backend/hub/services/models/local_inventory.py:998

    # the retry path, so there is always one) instead of rescanning forever.
    logger.warning("Local inventory kept racing cache invalidations; serving the last scan")
    return classify(superseded)


def get_models_folder_response() -> dict:
    """Return the directory where downloaded models are stored.

    This is the active HF hub cache (honors ``HF_HOME`` / ``HF_HUB_CACHE``);
    the desktop app reveals it in the OS file manager.
    """
    path = _resolve_hf_cache_dir()
    # Create it if missing so "Open folder" works before the first download:
    # HF builds the cache lazily, and studio only pre-creates the *default*
    # dir, not a user's explicit HF_HOME / HF_HUB_CACHE.
    try:
        path.mkdir(parents = True, exist_ok = True)
    except OSError as e:
        raise HTTPException(
            status_code = 500,
            detail = f"Failed to create models folder: {path}: {e}",
        ) from e
    if not path.is_dir():
        raise HTTPException(
            status_code = 500,
            detail = f"Models folder path is not a directory: {path}",
        )
    return {"path": str(path)}


def get_scan_folders_response() -> dict:
    return {"folders": list_scan_folders()}


def add_scan_folder_response(path: str) -> dict:
    try:
        folder, inserted = add_scan_folder_with_status(_coerce_scan_folder_path(path))

View on GitHub (pinned to 203007d190)

Solutions

1. Point HF_HOME/HF_HUB_CACHE at a directory the backend user can write (mkdir -p && chown as that user to verify).
2. Clear the ENOTDIR case: remove the plain file that sits where a directory component is expected.
3. Free disk space or enlarge the volume if errno is ENOSPC.
4. If env config is wrong, unset HF_HOME so the default (writable) cache location is used.

Example fix

# before: HF_HOME=/etc/hf-cache  (root-owned)
sudo mkdir -p /var/lib/studio/hf-cache && sudo chown studio: /var/lib/studio/hf-cache
# after: HF_HOME=/var/lib/studio/hf-cache

import os

def hf_cache_is_writable() -> bool:
    base = os.environ.get("HF_HOME") or os.path.expanduser("~/.cache/huggingface")
    try:
        os.makedirs(base, exist_ok=True)
        probe = os.path.join(base, ".write-probe")
        with open(probe, "w") as f:
            f.write("x")
        os.remove(probe)
        return True
    except OSError:
        return False

When it happens

Trigger: Calling the 'reveal models folder' endpoint when HF_HOME points somewhere unwritable, e.g. /etc/hf, a read-only volume, a path where a regular file occupies a directory component (ENOTDIR), or the disk is full.

Common situations: Setting HF_HOME in a systemd unit to a directory owned by root while the service runs as a non-root user; containers with a read-only mount at the configured location; CI environments with tiny tmpfs disks.

Related errors

• Failed to read the local dataset cache.
• Failed to delete dataset from {len(failures)} cache location
• Models folder path is not a directory: {path}
• Path is not readable
• failed to delete uploaded files

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