unslothai/unsloth · warning · ValueError

The filesystem root cannot be registered

Error message

The filesystem root cannot be registered

What it means

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.

Source

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

    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
    if contains_sensitive_path_component(normalized):
        raise ValueError("Credential or configuration directories are not allowed")
    if is_denied_system_path(normalized):
        raise ValueError("System directories are not allowed")
    return normalized


def _root_identity(root: str) -> tuple[int, int]:
    try:
        root_stat = os.lstat(root)
    except OSError as exc:
        raise RuntimeError("Linked folder is unavailable") from exc
    if stat.S_ISLNK(root_stat.st_mode) or not stat.S_ISDIR(root_stat.st_mode):

View on GitHub (pinned to 203007d190)

Solutions

1. Choose a specific subdirectory (e.g. /home/user/Documents) rather than / or a drive root.
2. Restrict the folder picker's start directory and disable selecting mount roots.
3. If you truly need wide coverage, register several curated top-level folders individually.

Example fix

# before
validate_folder_path('/')

# after
validate_folder_path('/home/user/Documents')

import os
from utils.paths.external_media import is_local_filesystem_root

def folder_is_not_fs_root(path: str) -> bool:
    normalized = os.path.realpath(os.path.abspath(os.path.expanduser(path)))
    return not is_local_filesystem_root(normalized)

try:
    validate_folder_path(path)
except ValueError as e:
    if "filesystem root" not in str(e):
        raise
    return bad_request("select a specific folder, not the drive/filesystem root")

When it happens

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

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

Related errors

• Path does not exist
• Path must be a directory, not a file
• Path is not readable
• The entire home folder cannot be registered
• local cache path is too long (max 4096 chars)

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