abhigyanpatwari/GitNexus · error · ValueError

candidate overlay path exceeds {MAX_CANDIDATE_PATH_BYTES} by

Error message

candidate overlay path exceeds {MAX_CANDIDATE_PATH_BYTES} bytes: {relative}

What it means

Thrown by candidate_overlay_files (evolution.py:300) when a single file's POSIX-relative path, UTF-8 encoded, exceeds MAX_CANDIDATE_PATH_BYTES (512 bytes). This bounds per-path memory and path-based attack surface; an excessively deep or long-named file is rejected during the walk.

Source

Thrown at eval/workflow_bench/evolution.py:300

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

    for path in entries:
        relative = path.relative_to(overlay)

View on GitHub (pinned to d540b00184)

Solutions

Shorten the filename and/or flatten the directory structure under .claude/skills/gitnexus-{plan,work}/.
Rename machine-generated long paths to concise human-readable ones.
Verify len(rel.as_posix().encode()) <= 512 before submitting.

Example fix

# before: deeply nested long-named file
.claude/skills/gitnexus-work/<512+ byte path>/SKILL.md

# after: flatten and rename
from pathlib import PurePosixPath
rel = PurePosixPath('.claude/skills/gitnexus-work/SKILL.md')
assert len(rel.as_posix().encode()) <= 512, 'path too long'

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import PurePosixPath
from workflow_bench.evolution import MAX_CANDIDATE_PATH_BYTES

def paths_within_byte_limit(root):
    from pathlib import Path
    ok = True
    for p in Path(root).rglob('*'):
        rel = PurePosixPath(p.relative_to(root).as_posix())
        if len(rel.as_posix().encode()) > MAX_CANDIDATE_PATH_BYTES:
            ok = False
    return ok

Type guard

null

Try / catch

try:
    apply_candidate_overlay(overlay, worktree, sandbox=sandbox)
except ValueError as exc:
    if 'path exceeds' in str(exc):
        # shorten/flatten the named path, then retry
        ...

Prevention

Use short, human-readable filenames in the overlay.
Avoid deeply nested directory chains under the skill root.
Pre-check len(rel.encode()) <= 512 (MAX_CANDIDATE_PATH_BYTES).

When it happens

Trigger: An overlay file with an extremely long name or a very deep directory chain whose relative POSIX path exceeds 512 bytes when encoded.

Common situations: Auto-generated/hashed filenames; deeply nested directory structures; a script that embeds long descriptions into paths.

Related errors

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