unslothai/unsloth · error · ValueError

Linked folders in the same scope cannot overlap

Error message

Linked folders in the same scope cannot overlap

What it means

create_folder rejects a path when _paths_overlap finds it is a parent/child (or samefile alias via different mount points/bind mounts) of any existing linked folder in the same scope. Overlapping roots would double-ingest files and make delete/retire bookkeeping ambiguous, so each scope's folders must form a forest of disjoint subtrees.

Source

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

        try:
            conn.execute("BEGIN IMMEDIATE")
            if conn.execute(
                "SELECT 1 FROM linked_folder_retired_scopes WHERE scope=?", (scope,)
            ).fetchone():
                raise ValueError("The linked-folder scope no longer exists")
            normalized_key = _path_key(normalized)
            existing = conn.execute(
                "SELECT * FROM linked_folders WHERE scope=?", (scope,)
            ).fetchall()
            for row in existing:
                existing_key = _path_key(row["path"])
                if existing_key == normalized_key or _same_file(row["path"], normalized):
                    if row["status"] == "retired" or row["delete_remove_index"] is not None:
                        raise ValueError("Linked folder is still being removed")
                    conn.rollback()
                    return _reauthorize_folder(row["id"], normalized, expected_identity)
                if _paths_overlap(existing_key, normalized_key):
                    raise ValueError("Linked folders in the same scope cannot overlap")
            try:
                current_identity = _root_identity(normalized)
            except RuntimeError as exc:
                raise ValueError(str(exc)) from exc
            if current_identity != (root_device, root_inode) or (
                expected_identity is not None and current_identity != expected_identity
            ):
                raise ValueError("Linked folder changed after it was selected")
            conn.execute(
                "INSERT INTO linked_folders(id, scope_type, scope_id, scope, path, name, "
                "root_device, root_inode, auto_sync, status, created_at, updated_at) "
                "VALUES(?,?,?,?,?,?,?,?,?,?,?,?)",
                (
                    folder_id,
                    scope_type,
                    scope_id,
                    scope,
                    normalized,

View on GitHub (pinned to 203007d190)

Solutions

1. Link a sibling directory outside the existing folder's subtree, or use the existing parent link and rely on it for the subfolder.
2. Remove the overlapping existing folder first (remove_folder) and then register the narrower/wider path you actually want.
3. On Windows, normalize casing and separators before comparing so accidental 'overlap' from case-insensitivity is not created in the first place.

Example fix

# before: /home/user already linked in this KB
create_folder(scope_type="knowledge_base", scope_id=sid, path="/home/user/docs")

# after: link a disjoint sibling
create_folder(scope_type="knowledge_base", scope_id=sid, path="/home/user-archive/docs")

from pathlib import Path

def overlaps_existing(new_path: str, existing_paths: list[str]) -> bool:
    a = Path(os.path.realpath(new_path))
    for p in existing_paths:
        b = Path(os.path.realpath(p))
        if a == b or a in b.parents or b in a.parents:
            return True
    return False

try:
    create_folder(...)
except ValueError as e:
    if "cannot overlap" in str(e):
        show_user("This folder is inside (or contains) an already linked folder in this scope.")
    else:
        raise

When it happens

Trigger: Adding /home/user/docs when /home/user is already linked in the same KB; adding a subfolder of an existing link; adding a parent of an existing link; two different paths that os.path.samefile resolves to one inode (bind mounts, case-insensitive filesystems, 8.3 short names on Windows).

Common situations: Users trying to sync one small subfolder for 'faster' indexing while the parent is linked; Windows paths differing only by case or slash style; symlinks aliasing into an existing link (samefile detection).

Related errors

• Linked folder no longer resolves to its registered path
• Linked folders support only knowledge-base and project scope
• The linked-folder scope no longer exists
• Linked folder changed after it was selected
• Folder name cannot be empty

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