{"record":{"id":"22139f9715b1a952","repo":"unslothai/unsloth","slug":"the-filesystem-root-cannot-be-registered","errorCode":null,"errorMessage":"The filesystem root cannot be registered","messagePattern":"The filesystem root cannot be registered","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"warning","filePath":"studio/backend/core/rag/folder_sync.py","lineNumber":152,"sourceCode":"    except OSError as exc:\n        raise ValueError(\"Path does not exist\") from exc\n    normalized = os.path.realpath(expanded)\n    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):","sourceCodeStart":134,"sourceCodeEnd":170,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/rag/folder_sync.py#L134-L170","documentation":"ValueError raised when is_local_filesystem_root(normalized) reports the path is a filesystem root (e.g. '/', 'C:\\', a drive mount root). Registering a filesystem root as a linked folder would make the scanner walk the entire disk — including system files, credentials, and virtual filesystems — so it is categorically denied before any other policy check.","triggerScenarios":"Calling validate_folder_path('/'), validate_folder_path('C:\\\\'), or a bare mount point like '/mnt/usb' that is itself a filesystem root; users selecting the topmost entry in a folder picker.","commonSituations":"Users trying to index 'everything'; folder-picker UIs that let you confirm on the root node; paths that resolve to a mounted drive root after realpath.","solutions":["Choose a specific subdirectory (e.g. /home/user/Documents) rather than / or a drive root.","Restrict the folder picker's start directory and disable selecting mount roots.","If you truly need wide coverage, register several curated top-level folders individually."],"exampleFix":"# before\nvalidate_folder_path('/')\n\n# after\nvalidate_folder_path('/home/user/Documents')","handlingStrategy":"validation","validationCode":"import os\nfrom utils.paths.external_media import is_local_filesystem_root\n\ndef folder_is_not_fs_root(path: str) -> bool:\n    normalized = os.path.realpath(os.path.abspath(os.path.expanduser(path)))\n    return not is_local_filesystem_root(normalized)","typeGuard":null,"tryCatchPattern":"try:\n    validate_folder_path(path)\nexcept ValueError as e:\n    if \"filesystem root\" not in str(e):\n        raise\n    return bad_request(\"select a specific folder, not the drive/filesystem root\")","preventionTips":["Constrain folder pickers to start inside the user's home and disable root-node confirmation.","Reject single-component paths ('/', 'C:\\\\', '/mnt') client-side.","Register curated subfolders rather than whole volumes."],"tags":["paths","validation","filesystem","scope-guard"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}