{"record":{"id":"165c3e9d287cc13c","repo":"unslothai/unsloth","slug":"path-must-be-a-directory-not-a-file","errorCode":null,"errorMessage":"Path must be a directory, not a file","messagePattern":"Path must be a directory, not a file","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"warning","filePath":"studio/backend/core/rag/folder_sync.py","lineNumber":148,"sourceCode":"    expanded = os.path.abspath(os.path.expanduser(path))\n    try:\n        if stat.S_ISLNK(os.lstat(expanded).st_mode):\n            raise ValueError(\"Symbolic-link folders are not allowed\")\n    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:","sourceCodeStart":130,"sourceCodeEnd":166,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/rag/folder_sync.py#L130-L166","documentation":"ValueError raised when the fully normalized path (after realpath resolution of symlinks and . /..) exists but is not a directory — i.e. it is a regular file (or special file). The folder-link feature scans directory trees, so registering a file has no meaningful semantics and is rejected explicitly with a message distinguishing it from 'does not exist'.","triggerScenarios":"Calling validate_folder_path on a path to a .txt/.pdf file instead of its containing folder; drag-and-drop of a file (not folder) from an OS file picker into the link form; a path whose final component was replaced by a file after earlier validation.","commonSituations":"Users pasting a document path instead of its directory; file pickers configured without directory-only mode; frontend passing the wrong field (file path instead of folder path).","solutions":["Pass the containing directory of the file you want indexed — the scanner recurses into it.","Configure the client-side folder picker to directory-selection mode.","If a directory was expected, check whether something replaced it with a file of the same name."],"exampleFix":"# before\nvalidate_folder_path('/home/me/docs/report.pdf')\n\n# after\nvalidate_folder_path('/home/me/docs')  # scanner indexes files inside","handlingStrategy":"validation","validationCode":"import os\n\ndef folder_is_directory(path: str) -> bool:\n    expanded = os.path.realpath(os.path.abspath(os.path.expanduser(path)))\n    return os.path.isdir(expanded)","typeGuard":null,"tryCatchPattern":"try:\n    validate_folder_path(path)\nexcept ValueError as e:\n    if \"must be a directory\" not in str(e):\n        raise\n    import os\n    validate_folder_path(os.path.dirname(os.path.abspath(path)))  # register parent dir","preventionTips":["Use a directory-only picker (e.g. webkitdirectory / SHBrowseForFolders), not a file input.","Submit dirname(file) when users drag a single document.","Validate isdir on the client before the round-trip."],"tags":["paths","validation","user-input","filesystem"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}