{"record":{"id":"0f9e4008569b7811","repo":"unslothai/unsloth","slug":"failed-to-create-models-folder-path-e","errorCode":null,"errorMessage":"Failed to create models folder: {path}: {e}","messagePattern":"Failed to create models folder: (.+?): (.+?)","errorType":"http","errorClass":"HTTPException","httpStatus":500,"severity":"error","filePath":"studio/backend/hub/services/models/local_inventory.py","lineNumber":998,"sourceCode":"    # the retry path, so there is always one) instead of rescanning forever.\n    logger.warning(\"Local inventory kept racing cache invalidations; serving the last scan\")\n    return classify(superseded)\n\n\ndef get_models_folder_response() -> dict:\n    \"\"\"Return the directory where downloaded models are stored.\n\n    This is the active HF hub cache (honors ``HF_HOME`` / ``HF_HUB_CACHE``);\n    the desktop app reveals it in the OS file manager.\n    \"\"\"\n    path = _resolve_hf_cache_dir()\n    # Create it if missing so \"Open folder\" works before the first download:\n    # HF builds the cache lazily, and studio only pre-creates the *default*\n    # dir, not a user's explicit HF_HOME / HF_HUB_CACHE.\n    try:\n        path.mkdir(parents = True, exist_ok = True)\n    except OSError as e:\n        raise HTTPException(\n            status_code = 500,\n            detail = f\"Failed to create models folder: {path}: {e}\",\n        ) from e\n    if not path.is_dir():\n        raise HTTPException(\n            status_code = 500,\n            detail = f\"Models folder path is not a directory: {path}\",\n        )\n    return {\"path\": str(path)}\n\n\ndef get_scan_folders_response() -> dict:\n    return {\"folders\": list_scan_folders()}\n\n\ndef add_scan_folder_response(path: str) -> dict:\n    try:\n        folder, inserted = add_scan_folder_with_status(_coerce_scan_folder_path(path))","sourceCodeStart":980,"sourceCodeEnd":1016,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/hub/services/models/local_inventory.py#L980-L1016","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Point HF_HOME/HF_HUB_CACHE at a directory the backend user can write (mkdir -p && chown as that user to verify).","Clear the ENOTDIR case: remove the plain file that sits where a directory component is expected.","Free disk space or enlarge the volume if errno is ENOSPC.","If env config is wrong, unset HF_HOME so the default (writable) cache location is used."],"exampleFix":"# before: HF_HOME=/etc/hf-cache  (root-owned)\nsudo mkdir -p /var/lib/studio/hf-cache && sudo chown studio: /var/lib/studio/hf-cache\n# after: HF_HOME=/var/lib/studio/hf-cache","handlingStrategy":"validation","validationCode":"import os\n\ndef hf_cache_is_writable() -> bool:\n    base = os.environ.get(\"HF_HOME\") or os.path.expanduser(\"~/.cache/huggingface\")\n    try:\n        os.makedirs(base, exist_ok=True)\n        probe = os.path.join(base, \".write-probe\")\n        with open(probe, \"w\") as f:\n            f.write(\"x\")\n        os.remove(probe)\n        return True\n    except OSError:\n        return False","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Smoke-test HF_HOME writability at service startup (mkdir + touch probe) before the first request.","Never point HF_HOME at root-owned or read-only paths in unit files.","Monitor disk space on the cache volume — ENOSPC hits mkdir too."],"tags":["filesystem","http-500","hf-cache","permissions","environment-variables"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}