abhigyanpatwari/GitNexus · error · ValueError

candidate overlay exceeds the {MAX_CANDIDATE_FILES}-file lim

Error message

candidate overlay exceeds the {MAX_CANDIDATE_FILES}-file limit

What it means

Thrown by candidate_overlay_files (evolution.py:310) when the count of collected regular files exceeds MAX_CANDIDATE_FILES (64). This is the file-count cap, separate from the 256-entry cap (which also counts directories). The check runs after each file is appended to the entries list.

Source

Thrown at eval/workflow_bench/evolution.py:310

        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:
        raise ValueError(f"candidate overlay contains no files: {overlay}")

    for path in entries:
        relative = path.relative_to(overlay)
        parts = relative.parts
        if (
            len(parts) < 4
            or parts[:2] != (".claude", "skills")
            or parts[2] not in CANDIDATE_SKILLS
            or path.suffix.lower() != ".md"
        ):
            raise ValueError(
                "candidate overlays may only contain Markdown files under "
                ".claude/skills/gitnexus-{plan,work}: "

View on GitHub (pinned to d540b00184)

Solutions

  1. Reduce the overlay to only the necessary .claude/skills/gitnexus-{plan,work}/*.md files.
  2. Consolidate many small Markdown fragments into fewer files.
  3. Count files up front: assert len(candidate_overlay_files(overlay)) <= 64 before the real run.

Example fix

# before: 90 markdown files in the overlay -> exceeds 64-file limit

# after: consolidate to <=64 real skill files
from pathlib import Path
files = [p for p in Path('overlay').rglob('*.md')]
assert len(files) <= 64, f'{len(files)} files, cap is 64'
Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path
from workflow_bench.evolution import MAX_CANDIDATE_FILES

def file_count_ok(root: Path) -> bool:
    return sum(1 for p in Path(root).rglob('*') if p.is_file()) <= MAX_CANDIDATE_FILES

Type guard

null

Try / catch

try:
    apply_candidate_overlay(overlay, worktree, sandbox=sandbox)
except ValueError as exc:
    if 'file limit' in str(exc):
        # remove non-skill files, then retry
        ...

Prevention

When it happens

Trigger: More than 64 regular files anywhere in the overlay tree. Typically caused by including non-skill files, generated fragments, or many small prompt shards.

Common situations: Copying extra docs, examples, or generated snippets into the overlay; splitting a single skill into dozens of tiny includes; accidentally bundling unrelated skill sets.

Related errors

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