abhigyanpatwari/GitNexus · warning · ValueError

workspace snapshot exceeds its bounded entry or path limit

Error message

workspace snapshot exceeds its bounded entry or path limit

What it means

Raised in workspace_snapshot (runner_artifacts.py:151) when the number of entries exceeds MAX_WORKSPACE_SNAPSHOT_ENTRIES (100_000) or the cumulative relative-path byte length exceeds MAX_WORKSPACE_SNAPSHOT_PATH_BYTES (16 MiB). The bound exists so a pathological workspace (huge node_modules, generated corpus) cannot make the phase-boundary snapshot unbounded in time or memory.

Source

Thrown at eval/workflow_bench/runner_artifacts.py:151

    pending: list[tuple[Path, PurePosixPath]] = [(root, PurePosixPath())]
    entry_count = 0
    path_bytes = 0
    file_bytes = 0
    nofollow = getattr(os, "O_NOFOLLOW", 0)
    while pending:
        directory, relative_dir = pending.pop()
        try:
            children = sorted(os.scandir(directory), key=lambda entry: entry.name, reverse=True)
        except OSError as exc:
            raise ValueError(f"workspace snapshot directory is unreadable: {directory}: {exc}") from exc
        for entry in children:
            relative = relative_dir / entry.name
            if _is_bootstrap_noise(relative):
                continue
            entry_count += 1
            path_bytes += len(relative.as_posix().encode())
            if entry_count > MAX_WORKSPACE_SNAPSHOT_ENTRIES or path_bytes > MAX_WORKSPACE_SNAPSHOT_PATH_BYTES:
                raise ValueError("workspace snapshot exceeds its bounded entry or path limit")
            metadata = entry.stat(follow_symlinks=False)
            permissions = stat.S_IMODE(metadata.st_mode)
            if stat.S_ISDIR(metadata.st_mode):
                snapshot[relative.as_posix()] = f"d:{permissions:o}"
                pending.append((Path(entry.path), relative))
                continue
            if stat.S_ISLNK(metadata.st_mode):
                snapshot[relative.as_posix()] = f"l:{permissions:o}:{os.readlink(entry.path)}"
                continue
            if not stat.S_ISREG(metadata.st_mode):
                snapshot[relative.as_posix()] = f"s:{metadata.st_mode}"
                continue
            file_bytes += metadata.st_size
            if file_bytes > MAX_WORKSPACE_SNAPSHOT_FILE_BYTES:
                raise ValueError("workspace snapshot exceeds its bounded file-byte limit")
            descriptor = os.open(entry.path, os.O_RDONLY | nofollow)
            try:
                opened = os.fstat(descriptor)

View on GitHub (pinned to d540b00184)

Solutions

1. Reduce workspace footprint: exclude generated/vendored trees from the worktree by adding them to a .gitignore so the clone is lean, or run the snapshot before vendoring.
2. If the large tree is legitimate, raise MAX_WORKSPACE_SNAPSHOT_ENTRIES / MAX_WORKSPACE_SNAPSHOT_PATH_BYTES in runner_artifacts.py (note the snapshot is O(n) at every phase boundary).
3. Move bulky generated artifacts to a directory outside the worktree that the snapshot does not walk.

Example fix

// before: npm install bloats the worktree past 100k entries
setup: npm install

// after: install outside the hashed worktree, or add to .gitignore
echo 'node_modules/' >> .gitignore
# and install into a sibling dir referenced by NODE_PATH

from pathlib import Path
from eval.workflow_bench.runner_artifacts import MAX_WORKSPACE_SNAPSHOT_ENTRIES, MAX_WORKSPACE_SNAPSHOT_PATH_BYTES

def estimate_snapshot_cost(root: Path) -> tuple[int, int]:
    entries = 0
    path_bytes = 0
    for p in Path(root).rglob("*"):
        rel = p.relative_to(root).as_posix()
        if rel.startswith(".git/"):
            continue
        entries += 1
        path_bytes += len(rel.encode())
    return entries, path_bytes

entries, path_bytes = estimate_snapshot_cost(worktree)
assert entries <= MAX_WORKSPACE_SNAPSHOT_ENTRIES, f"{entries} entries > limit"
assert path_bytes <= MAX_WORKSPACE_SNAPSHOT_PATH_BYTES, f"{path_bytes} path bytes > limit"

When it happens

Trigger: The worktree contains more than 100k tracked entries (after .git and bootstrap-noise exclusion) or >16 MiB of path strings. Common with a deeply nested vendored dependency tree, a generated coverage/ directory, or a task setup that vendors a large SDK into the worktree.

Common situations: Task setup runs npm install into the worktree adding 200k node_modules entries; a corpus fixture checked into the repo; a build step emitting thousands of .o files; benchmarking a monorepo with many packages.

Related errors

• workspace snapshot exceeds its bounded file-byte limit
• workspace snapshot root must be a real directory: {root}
• workspace snapshot directory is unreadable: {directory}: {ex
• sandbox_copy exceeds the total byte limit
• Could not read ${GITNEXUS_RC_FILENAME}: ${(err as Error).mes

AI-assisted analysis of abhigyanpatwari/GitNexus@d540b00184 (2026-08-12). Data as JSON: /api/errors/cfb9e1416285efb4. Report an issue: GitHub.