abhigyanpatwari/GitNexus · error · ValueError

candidate overlay entries must be regular files: {relative}

Error message

candidate overlay entries must be regular files: {relative}

What it means

Thrown by candidate_overlay_files (evolution.py:307) for an entry that is neither a symlink, nor a directory, nor a regular file — i.e. a special file such as a FIFO, device node, or Unix socket. The overlay may contain only regular files (and directories to hold them).

Source

Thrown at eval/workflow_bench/evolution.py:307

            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)
        parts = relative.parts
        if (
            len(parts) < 4
            or parts[:2] != (".claude", "skills")
            or parts[2] not in CANDIDATE_SKILLS
            or path.suffix.lower() != ".md"
        ):

View on GitHub (pinned to d540b00184)

Solutions

  1. Remove the special file from the overlay.
  2. Audit the overlay with stat: reject anything that is not stat.S_ISREG or stat.S_ISDIR.
  3. Recreate the overlay from clean Markdown sources.

Example fix

# before: overlay contains a fifo/socket
overlay/.claude/skills/gitnexus-work/job.fifo

# after: strip non-regular, non-dir entries
import os, stat
from pathlib import Path
for p in Path('overlay').rglob('*'):
    m = p.lstat().st_mode
    if not (stat.S_ISREG(m) or stat.S_ISDIR(m)):
        p.unlink()
Defensive patterns

Strategy: validation

Validate before calling

import stat
from pathlib import Path

def overlay_has_only_regular_and_dirs(root: Path) -> bool:
    for p in Path(root).rglob('*'):
        m = p.lstat().st_mode
        if not (stat.S_ISREG(m) or stat.S_ISDIR(m)):
            return False
    return True

Type guard

null

Try / catch

try:
    apply_candidate_overlay(overlay, worktree, sandbox=sandbox)
except ValueError as exc:
    if 'must be regular files' in str(exc):
        # remove the named fifo/device/socket, then retry
        ...

Prevention

When it happens

Trigger: The overlay contains a FIFO, character/block device, or socket created by a stray shell command, test fixture, or accidental mkfifo.

Common situations: A leftover mkfifo from a test; a device node copied inadvisably; a socket file dropped by a daemon into the overlay directory.

Related errors

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