abhigyanpatwari/GitNexus · error · ValueError

candidate overlay exceeds the {MAX_CANDIDATE_ENTRIES}-entry

Error message

candidate overlay exceeds the {MAX_CANDIDATE_ENTRIES}-entry limit

What it means

Thrown by candidate_overlay_files (evolution.py:296) when the running count of scandir entries (files plus directories) across the entire overlay tree exceeds MAX_CANDIDATE_ENTRIES (256). The count increments per item returned by scandir in any directory, so it is the total tree entry count, not just files.

Source

Thrown at eval/workflow_bench/evolution.py:296

    if resolved_overlay != overlay:
        raise ValueError(f"candidate overlay cannot traverse symlinks: {overlay}")
    _require_real_directory(overlay, label="candidate overlay")

    entries: list[Path] = []
    pending = [overlay]
    entry_count = 0
    while pending:
        directory = pending.pop()
        child_directories: list[Path] = []
        try:
            iterator = os.scandir(directory)
        except OSError as exc:
            raise ValueError(f"candidate overlay directory is unreadable: {directory}: {exc}") from exc
        with iterator:
            for item in iterator:
                entry_count += 1
                if entry_count > MAX_CANDIDATE_ENTRIES:
                    raise ValueError(f"candidate overlay exceeds the {MAX_CANDIDATE_ENTRIES}-entry limit")
                path = Path(item.path)
                relative = path.relative_to(overlay)
                if len(relative.as_posix().encode()) > MAX_CANDIDATE_PATH_BYTES:
                    raise ValueError(f"candidate overlay path exceeds {MAX_CANDIDATE_PATH_BYTES} bytes: {relative}")
                if item.is_symlink():
                    raise ValueError(f"candidate overlay cannot contain symlinks: {relative}")
                if item.is_dir(follow_symlinks=False):
                    child_directories.append(path)
                    continue
                if not item.is_file(follow_symlinks=False):
                    raise ValueError(f"candidate overlay entries must be regular files: {relative}")
                entries.append(path)
                if len(entries) > MAX_CANDIDATE_FILES:
                    raise ValueError(f"candidate overlay exceeds the {MAX_CANDIDATE_FILES}-file limit")
        pending.extend(child_directories)

    entries.sort(key=lambda path: path.relative_to(overlay).as_posix())
    if not entries:

View on GitHub (pinned to d540b00184)

Solutions

  1. Strip everything except the .claude/skills/gitnexus-{plan,work}/*.md files from the overlay.
  2. Remove node_modules/.git/build/dist directories from the overlay.
  3. Rebuild the overlay from scratch containing only the intended Markdown prompts.

Example fix

# before: overlay contains a copied repo -> thousands of entries

# after: keep only the skill markdown files
import shutil
from pathlib import Path
clean = Path('overlay-clean')
clean.mkdir()
for p in Path('overlay').rglob('*.md'):
    rel = p.relative_to('overlay')
    if rel.parts[:2] == ('.claude', 'skills'):
        dest = clean / rel
        dest.parent.mkdir(parents=True, exist_ok=True)
        shutil.copy2(p, dest)
Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path
from workflow_bench.evolution import MAX_CANDIDATE_ENTRIES

def entry_count_ok(root: Path) -> bool:
    count = 0
    for _ in root.rglob('*'):
        count += 1
        if count > MAX_CANDIDATE_ENTRIES:
            return False
    return True

Type guard

null

Try / catch

try:
    apply_candidate_overlay(overlay, worktree, sandbox=sandbox)
except ValueError as exc:
    if 'entry limit' in str(exc):
        # strip non-skill dirs (node_modules/.git/build), then retry
        ...

Prevention

When it happens

Trigger: An overlay tree with more than 256 entries total — usually because unrelated directories (node_modules, .git, build artifacts, a copied repo) were included alongside the skill prompts.

Common situations: Copying the whole repository or a node_modules tree into the overlay by mistake; nested generated output or caches inflating entry count; a build step that emitted thousands of files under the overlay.

Related errors

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