unslothai/unsloth · error · RuntimeError

The Hugging Face cache location is managed by an environment

Error message

The Hugging Face cache location is managed by an environment variable.

What it means

Raised by set_hf_cache_home() when _environment_paths() returns non-None, i.e. the process environment already pins the cache via HF_HOME, HF_HUB_CACHE, or HUGGINGFACE_HUB_CACHE. Because Hugging Face libraries honor the env vars first, a stored setting would be silently ignored, so the setter refuses rather than lie. Notably HF_XET_CACHE alone does not trigger it — only the home/hub vars do.

Source

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

    seen: set[str] = set()
    for value in raw:
        if not isinstance(value, str) or not value.strip():
            continue
        try:
            path = _canonical(value)
        except (OSError, RuntimeError, ValueError):
            continue
        key = os.path.normcase(str(path))
        if key in seen:
            continue
        seen.add(key)
        out.append(path)
    return out[:MAX_CACHE_HISTORY]


def set_hf_cache_home(cache_home: Optional[str]) -> HuggingFaceCachePaths:
    if _environment_paths() is not None:
        raise RuntimeError("The Hugging Face cache location is managed by an environment variable.")
    with _settings_lock:
        previous = _stored_cache_home()
        next_home = _validate_cache_home(cache_home) if cache_home is not None else None
        history = _stored_history()
        if previous is not None and previous != next_home:
            history.insert(0, previous)
        deduped: list[str] = []
        seen: set[str] = set()
        for path in history:
            key = os.path.normcase(str(path))
            if key in seen or path == next_home:
                continue
            seen.add(key)
            deduped.append(str(path))
            if len(deduped) >= MAX_CACHE_HISTORY:
                break
        from storage.studio_db import upsert_app_settings

View on GitHub (pinned to 203007d190)

Solutions

Unset the controlling variable and restart the backend: unset HF_HOME HF_HUB_CACHE HUGGINGFACE_HUB_CACHE (or remove it from the Dockerfile/systemd unit/compose env), then use the in-app setting
If you want the env var to win, simply do not call set_hf_cache_home — the app displays the environment-managed location (source 'environment')
Identify the controlling var: env | grep -E 'HF_HOME|HF_HUB_CACHE|HUGGINGFACE_HUB_CACHE'

Example fix

# before
HF_HUB_CACHE=/models unsloth studio
# then set_hf_cache_home('/data/hf') -> RuntimeError

# after
unset HF_HUB_CACHE HF_HOME HUGGINGFACE_HUB_CACHE
# restart backend, then
set_hf_cache_home('/data/hf')  # ok

Defensive patterns

Strategy: validation

Validate before calling

import os

def env_controls_cache() -> bool:
    return any(os.environ.get(k) for k in ('HF_HOME', 'HF_HUB_CACHE', 'HUGGINGFACE_HUB_CACHE'))

if env_controls_cache():
    hide_or_disable_cache_picker()  # environment wins; do not call set_hf_cache_home

Try / catch

try:
    set_hf_cache_home(path)
except RuntimeError:
    explain('cache location is pinned by HF_HOME/HF_HUB_CACHE env; unset it to change here')

Prevention

Do not bake HF_HOME into images that also use the in-app cache setting
Show the controlling variable name in the UI when present
Decide one source of truth (env or settings) per deployment

When it happens

Trigger: Calling set_hf_cache_home() with HF_HOME, HF_HUB_CACHE, or HUGGINGFACE_HUB_CACHE exported in the backend process's environment. Typical in Docker images that set HF_HOME=/models, CI runners, or shells where the user exported HF_HUB_CACHE before launching Studio. The check reads _EXPLICIT_CACHE_ENV captured from os.environ at module load.

Common situations: Docker/Kubernetes deployments baking in HF_HOME for image-layer caching; wrappers like 'HF_HUB_CACHE=... unsloth studio'; CI environments; users who set the var to work around a previous cache bug and forgot it.

Related errors

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