unslothai/unsloth · warning · ValueError

The managed RAG uploads folder cannot be linked

Error message

The managed RAG uploads folder cannot be linked

What it means

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.

Source

Thrown at studio/backend/core/rag/folder_sync.py:139

        return os.path.normcase(os.path.commonpath([root, path])) == os.path.normcase(root)
    except ValueError:
        return False


def validate_folder_path(path: str) -> str:
    """Apply the existing model scan-folder policy without persisting there."""
    if not path or not path.strip() or "\x00" in path:
        raise ValueError("Path cannot be empty")
    expanded = os.path.abspath(os.path.expanduser(path))
    try:
        if stat.S_ISLNK(os.lstat(expanded).st_mode):
            raise ValueError("Symbolic-link folders are not allowed")
    except OSError as exc:
        raise ValueError("Path does not exist") from exc
    normalized = os.path.realpath(expanded)
    uploads_root = os.path.realpath(str(rag_uploads_root()))
    if _paths_overlap(_path_key(normalized), _path_key(uploads_root)):
        raise ValueError("The managed RAG uploads folder cannot be linked")

    from hub.storage.scan_folders import (
        contains_sensitive_path_component,
        is_denied_system_path,
    )
    from utils.paths.external_media import is_local_filesystem_root

    if not os.path.isdir(normalized):
        raise ValueError("Path must be a directory, not a file")
    if not os.access(normalized, os.R_OK | os.X_OK):
        raise ValueError("Path is not readable")
    if is_local_filesystem_root(normalized):
        raise ValueError("The filesystem root cannot be registered")
    try:
        if Path(normalized) == Path.home().resolve():
            raise ValueError("The entire home folder cannot be registered")
    except RuntimeError:
        pass

View on GitHub (pinned to 203007d190)

Solutions

1. Link a dedicated folder outside the application data/uploads directory.
2. Locate the uploads root (rag_uploads_root()) and exclude it and its parents from user-selectable folders in the UI.
3. If you moved the uploads root, register folders that are not under the new root.

Example fix

# before
validate_folder_path('/home/me/.local/share/myapp/uploads')  # is the uploads root

# after
validate_folder_path('/home/me/Documents/rag-sources')  # separate source folder

import os
from core.rag.folder_sync import rag_uploads_root, _paths_overlap, _path_key

def folder_is_outside_uploads(path: str) -> bool:
    normalized = os.path.realpath(os.path.abspath(os.path.expanduser(path)))
    uploads = os.path.realpath(str(rag_uploads_root()))
    return not _paths_overlap(_path_key(normalized), _path_key(uploads))

try:
    validate_folder_path(path)
except ValueError as e:
    if "uploads folder" not in str(e):
        raise
    return bad_request("pick a source folder outside the app's upload storage")

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Path cannot be empty
• Symbolic-link folders are not allowed
• Path does not exist
• Path must be a directory, not a file
• Path is not readable

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/a67a7bfadcc7c951. Report an issue: GitHub.