{"record":{"id":"a67a7bfadcc7c951","repo":"unslothai/unsloth","slug":"the-managed-rag-uploads-folder-cannot-be-linked","errorCode":null,"errorMessage":"The managed RAG uploads folder cannot be linked","messagePattern":"The managed RAG uploads folder cannot be linked","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"warning","filePath":"studio/backend/core/rag/folder_sync.py","lineNumber":139,"sourceCode":"        return os.path.normcase(os.path.commonpath([root, path])) == os.path.normcase(root)\n    except ValueError:\n        return False\n\n\ndef validate_folder_path(path: str) -> str:\n    \"\"\"Apply the existing model scan-folder policy without persisting there.\"\"\"\n    if not path or not path.strip() or \"\\x00\" in path:\n        raise ValueError(\"Path cannot be empty\")\n    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","sourceCodeStart":121,"sourceCodeEnd":157,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/rag/folder_sync.py#L121-L157","documentation":"ValueError raised when the normalized candidate folder path overlaps the managed RAG uploads root (the app's own upload storage), detected via _paths_overlap on case-normalized path keys. Allowing users to link the uploads folder back into RAG as a source would create a recursive self-ingestion loop: ingested documents would be re-discovered as uploads, duplicating and potentially infinitely growing the store.","triggerScenarios":"Calling validate_folder_path with the exact uploads directory, a parent of it (e.g. the whole data dir), or a subdirectory inside it; deriving the path from config at runtime so it happens to coincide with the uploads root.","commonSituations":"Users trying to 'index everything' by pointing the linker at the application data folder; moving the uploads root via configuration and then registering the old location; choosing ~/Library/Application Support/<app> or %APPDATA%\\<app> as a linked folder.","solutions":["Link a dedicated folder outside the application data/uploads directory.","Locate the uploads root (rag_uploads_root()) and exclude it and its parents from user-selectable folders in the UI.","If you moved the uploads root, register folders that are not under the new root."],"exampleFix":"# before\nvalidate_folder_path('/home/me/.local/share/myapp/uploads')  # is the uploads root\n\n# after\nvalidate_folder_path('/home/me/Documents/rag-sources')  # separate source folder","handlingStrategy":"validation","validationCode":"import os\nfrom core.rag.folder_sync import rag_uploads_root, _paths_overlap, _path_key\n\ndef folder_is_outside_uploads(path: str) -> bool:\n    normalized = os.path.realpath(os.path.abspath(os.path.expanduser(path)))\n    uploads = os.path.realpath(str(rag_uploads_root()))\n    return not _paths_overlap(_path_key(normalized), _path_key(uploads))","typeGuard":null,"tryCatchPattern":"try:\n    validate_folder_path(path)\nexcept ValueError as e:\n    if \"uploads folder\" not in str(e):\n        raise\n    return bad_request(\"pick a source folder outside the app's upload storage\")","preventionTips":["Filter the app's own data directory (and its parents) out of the client folder browser.","Keep user content and app-managed storage on separate top-level paths by convention.","Re-run this overlap check whenever the uploads root is relocated in config."],"tags":["paths","rag","validation","recursion-guard"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}