abhigyanpatwari/GitNexus · error · ValueError

overlay destination must already be a regular file: {target}

Error message

overlay destination must already be a regular file: {target}

What it means

_read_destination rejects a mirror that does not already exist as a regular file: the first branch catches FileNotFoundError on path.lstat() and chains it into a ValueError naming the target. The destination must be pre-created by a prior promotion; this read is for verification, not first-write.

Source

Thrown at eval/workflow_bench/promotion_apply.py:113

    except BaseException:
        # A partially written candidate/backup is never eligible for later
        # cleanup through the replacements list, so remove it here before the
        # staging exception escapes.
        os.close(descriptor)
        staged.unlink(missing_ok=True)
        raise
    else:
        os.close(descriptor)
    return staged


def _read_destination(path: Path, *, target: PurePosixPath) -> tuple[bytes, int]:
    """Read one mirror without following links and reject concurrent mutation."""

    try:
        before = path.lstat()
    except FileNotFoundError as exc:
        raise ValueError(f"overlay destination must already be a regular file: {target}") from exc
    if stat.S_ISLNK(before.st_mode) or not stat.S_ISREG(before.st_mode):
        raise ValueError(f"overlay destination must already be a regular file: {target}")
    descriptor = os.open(path, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0))
    try:
        opened = os.fstat(descriptor)
        if not stat.S_ISREG(opened.st_mode):
            raise ValueError(f"overlay destination must already be a regular file: {target}")
        chunks: list[bytes] = []
        while chunk := os.read(descriptor, 64 * 1024):
            chunks.append(chunk)
        after = os.fstat(descriptor)
    finally:
        os.close(descriptor)
    try:
        final = path.lstat()
    except FileNotFoundError as exc:
        raise ValueError(f"overlay destination changed while being read: {target}") from exc

View on GitHub (pinned to d540b00184)

Solutions

1. Inspect the {target} path and confirm whether it should exist; if a mirror was added recently, re-run promotion from scratch.
2. Ensure no `git clean` / IDE file watcher removes mirror files between promotion and verification.
3. Re-run the full promotion pipeline so all mirrors are recreated atomically.
4. If the mirror list is intentionally stale, prune MIRROR_SKILL_ROOTS to match reality.

from pathlib import Path

def ensure_all_mirrors_exist(mirrors: list[Path]) -> None:
    missing = [str(p) for p in mirrors if not p.exists() or p.is_symlink()]
    if missing:
        raise SystemExit(f'mirrors missing or symlinked: {missing}; re-run full promotion')

try:
    data, mode = _read_destination(path, target=relative)
except ValueError as exc:
    if 'must already be a regular file' in str(exc) and 'No such file' in str(exc.__cause__):
        log.error('mirror %s missing; rerun full promotion', relative)
    raise

When it happens

Trigger: Calling _read_destination on a mirror path whose lstat raises FileNotFoundError — i.e. the promoted file was never written here, or was deleted before this read. Triggered when freeze_overlay/apply created some mirrors but not this one, or a sweep removed one.

Common situations: Partial promotion rollback left some mirrors missing; the MIRROR_SKILL_ROOTS list grew but the old snapshot predates a mirror; an external process (git clean, IDE) deleted one of the mirror files.

Related errors

• overlay snapshot destination already exists: {destination}
• overlay destination changed while being read: {target}
• frozen overlay bytes do not match the authorized input
• candidate destination parent must be a real directory: {rela
• candidate destination is unreadable: {relative}: {exc}

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