unslothai/unsloth · error · RuntimeError

Folder nesting exceeds the {_MAX_FOLDER_DEPTH}-level scan li

Error message

Folder nesting exceeds the {_MAX_FOLDER_DEPTH}-level scan limit

What it means

During the recursive directory walk in _scan, when a subdirectory is about to be queued at depth == _MAX_FOLDER_DEPTH (64), the scan aborts. The depth cap bounds work and stack growth in the pending-list BFS; loop protection via ancestor path/identity sets only shortcuts known cycles (mount-point aliases, resolved repeats), it does not authorize unbounded depth.

Source

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

                        not _is_within(root, resolved)
                        or contains_sensitive_path_component(os.path.relpath(resolved, root))
                        or is_denied_system_path(resolved)
                    ):
                        continue
                    resolved_key = _path_key(resolved)
                    if resolved_key in ancestor_paths:
                        continue
                    directory_stat = entry.stat(follow_symlinks = False)
                    directory_identity = (directory_stat.st_dev, directory_stat.st_ino)
                    identity_usable = directory_identity[1] not in (None, 0)
                    if (
                        identity_usable
                        and directory_identity in ancestor_identities
                        and (resolved_key in mount_points or os.path.ismount(full))
                    ):
                        continue
                    if depth >= _MAX_FOLDER_DEPTH:
                        raise RuntimeError(
                            f"Folder nesting exceeds the {_MAX_FOLDER_DEPTH}-level scan limit"
                        )
                    child_identities = ancestor_identities
                    if identity_usable:
                        child_identities = ancestor_identities | {directory_identity}
                    pending.append(
                        (
                            full,
                            ancestor_paths | {resolved_key},
                            child_identities,
                            depth + 1,
                        )
                    )
                    continue
                if not entry.is_file(follow_symlinks = False):
                    continue
                if os.path.splitext(entry.name)[1].lower() not in config.UPLOAD_EXTS:
                    continue

View on GitHub (pinned to 203007d190)

Solutions

Flatten or clean the deep subtree (delete runaway recursive copies such as folder/folder/folder/...).
Link a shallower subdirectory that excludes the deep chain instead of the whole tree.
If deeper trees are legitimate, raise _MAX_FOLDER_DEPTH in folder_sync.py consciously — the cap protects memory and job duration.

Example fix

# before
create_folder(..., path="/data/proj")  # contains a 100-level self-copy chain

# after
create_folder(..., path="/data/proj/src")  # shallow subtree, deep chain excluded

Defensive patterns

Strategy: validation

Validate before calling

_MAX_FOLDER_DEPTH = 64

def tree_depth_ok(root: str, cap: int = _MAX_FOLDER_DEPTH) -> bool:
    deepest = 0
    stack = [(root, 0)]
    while stack:
        d, depth = stack.pop()
        deepest = max(deepest, depth)
        if depth >= cap:
            return False
        if os.path.isdir(d):
            stack += [(os.path.join(d, e), depth + 1) for e in os.listdir(d)]
    return True

Try / catch

try:
    create_folder_with_sync(...)
except RuntimeError as e:
    if "scan limit" in str(e):
        show_user("Folder tree is nested deeper than 64 levels; flatten or link a shallower folder.")
    else:
        raise

Prevention

Check tree depth before linking very large trees.
Clean up accidental recursive self-copies (folder/folder/folder/...).
Link the specific subtree you need, not a monolithic root.

When it happens

Trigger: A genuinely nested tree deeper than 64 levels under the linked root (e.g. node_modules-style nesting, recursive build output, deliberately generated deep chains); symlink-loop protection does not fire because symlinks are skipped, so this is real directory depth.

Common situations: Build artifacts (target/debug/...), pathological npm/cargo trees, a script bug that recursively copies a folder into itself (creating real, not symlinked, depth).

Related errors

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