unslothai/unsloth · warning · ValueError

The filesystem root cannot be registered

Error message

The filesystem root cannot be registered

What it means

Validation error from add_scan_folder_with_status: is_local_filesystem_root(normalized) is True — the submitted path is a local filesystem root ('/' on POSIX, 'C:\' on Windows). Registering a root would let the folder browser enumerate the whole disk, including denied system directories, so it is refused. UNC share roots (\\server\share) are deliberately exempt because they contain no system dirs.

Source

Thrown at studio/backend/hub/storage/scan_folders.py:133

        conn.close()


def add_scan_folder_with_status(path: str) -> tuple[dict, bool]:
    """Add a readable scan folder and return its row plus whether it was inserted."""
    if not path or not path.strip():
        raise ValueError("Path cannot be empty")
    normalized = os.path.realpath(os.path.expanduser(normalize_path(path.strip())))

    if not os.path.exists(normalized):
        raise ValueError("Path does not exist")
    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):
        # A local fs root ("/", "C:\\") would expose denied system dirs via browse;
        # a UNC share root (\\server\share) has none under it and stays registerable.
        raise ValueError("The filesystem root cannot be registered")
    if _contains_sensitive_path_component(normalized):
        raise ValueError("Credential or configuration directories are not allowed")

    is_win = platform.system() == "Windows"
    check = os.path.normcase(normalized) if is_win else normalized
    for prefix in _denied_path_prefixes():
        if check == prefix or check.startswith(prefix + os.sep):
            if prefix == "/run" and is_linux_run_media_path(check):
                continue
            raise ValueError(f"Path under {prefix} is not allowed")

    conn = get_connection()
    try:
        _ensure_schema(conn)
        now = datetime.now(timezone.utc).isoformat()
        if is_win:
            existing = conn.execute(
                "SELECT id, path, created_at FROM scan_folders WHERE path = ? COLLATE NOCASE",

View on GitHub (pinned to 203007d190)

Solutions

1. Register specific top-level folders instead, e.g. /data, /mnt/models, D:\AI-models.
2. For a USB/external drive, register a folder on it rather than the drive root.
3. If whole-disk coverage is truly needed, register the handful of top-level directories individually (each still passes the denylist).

Example fix

# before
add_scan_folder('/')
# after
add_scan_folder('/data/models')
add_scan_folder('/home/user/hf-cache')

import ntpath, posixpath

def is_fs_root(path: str) -> bool:
    p = posixpath.normpath(path)
    if p == "/":
        return True
    drive, tail = ntpath.splitdrive(p)
    return bool(drive) and tail in ("", "\\", "/")

def registerable(path: str) -> bool:
    return not is_fs_root(path)

When it happens

Trigger: Registering '/', '/.', 'C:\', 'D:\', or any path that realpath collapses to a drive root.

Common situations: Users wanting 'scan everything'; a UI defaulting a path picker to the filesystem root; Windows users entering a drive letter without a subfolder.

Related errors

• Path under {prefix} is not allowed
• Credential or configuration directories are not allowed
• dataset path must be relative or under a dataset root: {raw!
• {_cn_fs.reason}
• Provider base URL points at a private address, which is disa

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