{"record":{"id":"7cf7a4f0eaa0e27b","repo":"unslothai/unsloth","slug":"the-hugging-face-cache-location-is-managed-by-an-e","errorCode":null,"errorMessage":"The Hugging Face cache location is managed by an environment variable.","messagePattern":"The Hugging Face cache location is managed by an environment variable\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"studio/backend/utils/hf_cache_settings.py","lineNumber":315,"sourceCode":"    seen: set[str] = set()\n    for value in raw:\n        if not isinstance(value, str) or not value.strip():\n            continue\n        try:\n            path = _canonical(value)\n        except (OSError, RuntimeError, ValueError):\n            continue\n        key = os.path.normcase(str(path))\n        if key in seen:\n            continue\n        seen.add(key)\n        out.append(path)\n    return out[:MAX_CACHE_HISTORY]\n\n\ndef set_hf_cache_home(cache_home: Optional[str]) -> HuggingFaceCachePaths:\n    if _environment_paths() is not None:\n        raise RuntimeError(\"The Hugging Face cache location is managed by an environment variable.\")\n    with _settings_lock:\n        previous = _stored_cache_home()\n        next_home = _validate_cache_home(cache_home) if cache_home is not None else None\n        history = _stored_history()\n        if previous is not None and previous != next_home:\n            history.insert(0, previous)\n        deduped: list[str] = []\n        seen: set[str] = set()\n        for path in history:\n            key = os.path.normcase(str(path))\n            if key in seen or path == next_home:\n                continue\n            seen.add(key)\n            deduped.append(str(path))\n            if len(deduped) >= MAX_CACHE_HISTORY:\n                break\n        from storage.studio_db import upsert_app_settings\n","sourceCodeStart":297,"sourceCodeEnd":333,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/utils/hf_cache_settings.py#L297-L333","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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'"],"exampleFix":"# before\nHF_HUB_CACHE=/models unsloth studio\n# then set_hf_cache_home('/data/hf') -> RuntimeError\n\n# after\nunset HF_HUB_CACHE HF_HOME HUGGINGFACE_HUB_CACHE\n# restart backend, then\nset_hf_cache_home('/data/hf')  # ok","handlingStrategy":"validation","validationCode":"import os\n\ndef env_controls_cache() -> bool:\n    return any(os.environ.get(k) for k in ('HF_HOME', 'HF_HUB_CACHE', 'HUGGINGFACE_HUB_CACHE'))\n\nif env_controls_cache():\n    hide_or_disable_cache_picker()  # environment wins; do not call set_hf_cache_home","typeGuard":null,"tryCatchPattern":"try:\n    set_hf_cache_home(path)\nexcept RuntimeError:\n    explain('cache location is pinned by HF_HOME/HF_HUB_CACHE env; unset it to change here')","preventionTips":["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"],"tags":["huggingface","cache","environment-variables","configuration","docker"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}