{"record":{"id":"36ce7979b35d3d4e","repo":"unslothai/unsloth","slug":"the-hugging-face-cache-folder-must-be-an-absolute","errorCode":null,"errorMessage":"The Hugging Face cache folder must be an absolute path.","messagePattern":"The Hugging Face cache folder must be an absolute path\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"studio/backend/utils/hf_cache_settings.py","lineNumber":248,"sourceCode":"    os.environ[\"HF_HUB_CACHE\"] = str(paths.hub_cache)\n    os.environ[\"HF_XET_CACHE\"] = str(paths.xet_cache)\n    if \"HUGGINGFACE_HUB_CACHE\" not in _EXPLICIT_CACHE_ENV:\n        os.environ.pop(\"HUGGINGFACE_HUB_CACHE\", None)\n    for directory in (paths.hub_cache, paths.xet_cache):\n        try:\n            directory.mkdir(parents = True, exist_ok = True)\n        except OSError:\n            pass\n    return paths\n\n\ndef _validate_cache_home(raw_path: str) -> Path:\n    value = raw_path.strip()\n    if not value:\n        raise ValueError(\"Choose a cache folder.\")\n    candidate = Path(value).expanduser()\n    if not candidate.is_absolute():\n        raise ValueError(\"The Hugging Face cache folder must be an absolute path.\")\n    try:\n        resolved = candidate.resolve(strict = False)\n    except (OSError, RuntimeError, ValueError) as exc:\n        raise ValueError(\"The Hugging Face cache folder is invalid.\") from exc\n\n    if resolved.parent == resolved:\n        raise ValueError(\"Choose a folder inside the filesystem or drive root.\")\n    try:\n        from hub.storage.scan_folders import (\n            contains_sensitive_path_component,\n            is_denied_system_path,\n        )\n    except ImportError:\n        contains_sensitive_path_component = is_denied_system_path = None\n    if is_denied_system_path is not None and is_denied_system_path(str(resolved)):\n        raise ValueError(\"System folders cannot be used for model downloads.\")\n    if contains_sensitive_path_component is not None and contains_sensitive_path_component(\n        str(resolved)","sourceCodeStart":230,"sourceCodeEnd":266,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/utils/hf_cache_settings.py#L230-L266","documentation":"Raised by _validate_cache_home when the (non-empty) cache folder value is a relative path. The Hugging Face cache must be pinned to a fixed absolute location so cache resolution stays stable regardless of the process working directory. This check runs after the empty check and before resolve()/sensitive-path checks.","triggerScenarios":"Passing a relative path like 'hf_cache', './cache/huggingface', or '~' without expansion context (note: expanduser IS applied, so '~/x' is fine, but 'x/y' is not) to the cache-home setter.","commonSituations":"Users entering a folder name in the settings UI instead of picking a folder; configs written with project-relative paths; porting configs between tools where relative cache dirs are common; cwd-dependent behavior breaking cache hits.","solutions":["Use an absolute path: /home/user/.cache/huggingface or C:\\\\Users\\\\me\\\\hf-cache.","If you have a relative path programmatically, absolutize it first: Path(p).expanduser().resolve().","In the UI, use a folder picker that returns absolute paths instead of free text.","For per-project caches, compute the absolute path from the project root before saving."],"exampleFix":"# before\nset_cache_home(\"hf_cache\")  # relative -> ValueError\n\n# after\nfrom pathlib import Path\nset_cache_home(str(Path(\"hf_cache\").resolve()))  # /proj/hf_cache","handlingStrategy":"validation","validationCode":"from pathlib import Path\n\ndef is_absolute_expanded(raw) -> bool:\n    try:\n        return Path(str(raw).strip()).expanduser().is_absolute()\n    except Exception:\n        return False\n\n# guard: assert is_absolute_expanded(raw) before set_cache_home(raw)","typeGuard":"def is_absolute_cache_path(value) -> bool:\n    if not isinstance(value, str) or not value.strip():\n        return False\n    return Path(value.strip()).expanduser().is_absolute()","tryCatchPattern":null,"preventionTips":["Always store cache folders as absolute paths; resolve relatives at config load.","Expand ~ with expanduser() yourself if you rely on shell-style inputs.","Use UI folder pickers over free-text entry for path settings.","Remember subsequent validation also rejects filesystem roots and sensitive system paths — pick a normal data directory."],"tags":["settings","hf-cache","path-validation","absolute-path"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}