{"record":{"id":"0193b31f81eb1913","repo":"unslothai/unsloth","slug":"the-entire-home-folder-cannot-be-registered","errorCode":null,"errorMessage":"The entire home folder cannot be registered","messagePattern":"The entire home folder cannot be registered","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"warning","filePath":"studio/backend/core/rag/folder_sync.py","lineNumber":155,"sourceCode":"    uploads_root = os.path.realpath(str(rag_uploads_root()))\n    if _paths_overlap(_path_key(normalized), _path_key(uploads_root)):\n        raise ValueError(\"The managed RAG uploads folder cannot be linked\")\n\n    from hub.storage.scan_folders import (\n        contains_sensitive_path_component,\n        is_denied_system_path,\n    )\n    from utils.paths.external_media import is_local_filesystem_root\n\n    if not os.path.isdir(normalized):\n        raise ValueError(\"Path must be a directory, not a file\")\n    if not os.access(normalized, os.R_OK | os.X_OK):\n        raise ValueError(\"Path is not readable\")\n    if is_local_filesystem_root(normalized):\n        raise ValueError(\"The filesystem root cannot be registered\")\n    try:\n        if Path(normalized) == Path.home().resolve():\n            raise ValueError(\"The entire home folder cannot be registered\")\n    except RuntimeError:\n        pass\n    if contains_sensitive_path_component(normalized):\n        raise ValueError(\"Credential or configuration directories are not allowed\")\n    if is_denied_system_path(normalized):\n        raise ValueError(\"System directories are not allowed\")\n    return normalized\n\n\ndef _root_identity(root: str) -> tuple[int, int]:\n    try:\n        root_stat = os.lstat(root)\n    except OSError as exc:\n        raise RuntimeError(\"Linked folder is unavailable\") from exc\n    if stat.S_ISLNK(root_stat.st_mode) or not stat.S_ISDIR(root_stat.st_mode):\n        raise RuntimeError(\"Linked folder is no longer a regular directory\")\n    if os.path.normcase(os.path.realpath(root)) != os.path.normcase(root):\n        raise RuntimeError(\"Linked folder no longer resolves to its registered path\")","sourceCodeStart":137,"sourceCodeEnd":173,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/rag/folder_sync.py#L137-L173","documentation":"ValueError raised when the normalized path equals the resolved user home directory (Path.home().resolve()). The home folder as a whole contains credential/config subdirectories and huge caches, so registering it wholesale is denied even though individual subfolders may be fine. The check is wrapped in try/except RuntimeError (pass) to tolerate environments where the home cannot be resolved (e.g. deleted home dir), degrading to the later component checks.","triggerScenarios":"Calling validate_folder_path('~') or the literal home path '/home/user' or '/Users/user'; a realpath that collapses (e.g. '~/.') back to home; folder pickers opened at home where the user confirms unchanged.","commonSituations":"Users wanting to index all their documents by linking home; cross-platform configs where '~' expansion lands exactly on home; freshly created accounts whose Documents live directly under home.","solutions":["Register the specific subfolder containing documents, e.g. ~/Documents or ~/Documents/rag.","If many folders under home are needed, register each one individually.","In UIs, pre-select a subfolder and reject a selection equal to the home path."],"exampleFix":"# before\nvalidate_folder_path('~')\n\n# after\nvalidate_folder_path('~/Documents')","handlingStrategy":"validation","validationCode":"import os\nfrom pathlib import Path\n\ndef folder_is_not_home(path: str) -> bool:\n    normalized = os.path.realpath(os.path.abspath(os.path.expanduser(path)))\n    try:\n        return Path(normalized) != Path.home().resolve()\n    except RuntimeError:\n        return True","typeGuard":null,"tryCatchPattern":"try:\n    validate_folder_path(path)\nexcept ValueError as e:\n    if \"home folder\" not in str(e):\n        raise\n    return bad_request(\"select a subfolder (e.g. Documents), not your entire home\")","preventionTips":["Default the picker to ~/Documents instead of ~ so users never confirm on home.","Reject the resolved home path client-side with a helpful message.","If broad coverage is needed, register a curated list of specific subfolders."],"tags":["paths","validation","home-directory","scope-guard"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}