abhigyanpatwari/GitNexus · error · ValueError

oracle source must be a bounded regular non-symlink file: {r

Error message

oracle source must be a bounded regular non-symlink file: {relative}

What it means

Raised by _read_oracle_file at the pre-open stage when the oracle source file itself is a symlink or not a regular file (lstat shows S_IFLNK or non-S_IFREG). The harness refuses to read anything that is not a plain regular file before it even calls os.open, as the first line of defense against symlink redirection.

Source

Thrown at eval/workflow_bench/oracle_assets.py:143

    return lexical


def _read_oracle_file(root: Path, relative: PurePosixPath) -> bytes:
    current = root
    for part in relative.parts[:-1]:
        current /= part
        try:
            metadata = current.lstat()
        except OSError as exc:
            raise ValueError(f"oracle parent is unreadable: {relative}") from exc
        if stat.S_ISLNK(metadata.st_mode) or not stat.S_ISDIR(metadata.st_mode):
            raise ValueError(f"oracle parents must be real directories: {relative}")

    path = root.joinpath(*relative.parts)
    try:
        before = path.lstat()
        if stat.S_ISLNK(before.st_mode) or not stat.S_ISREG(before.st_mode):
            raise ValueError(f"oracle source must be a bounded regular non-symlink file: {relative}")
        descriptor = os.open(path, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0))
    except ValueError:
        raise
    except OSError as exc:
        raise ValueError(f"oracle source is unreadable: {relative}") from exc
    try:
        opened = os.fstat(descriptor)
        if (
            stat.S_ISLNK(before.st_mode)
            or not stat.S_ISREG(before.st_mode)
            or not stat.S_ISREG(opened.st_mode)
            or before.st_dev != opened.st_dev
            or before.st_ino != opened.st_ino
            or opened.st_size > MAX_ORACLE_FILE_BYTES
        ):
            raise ValueError(f"oracle source must be a bounded regular non-symlink file: {relative}")
        chunks: list[bytes] = []
        remaining = MAX_ORACLE_FILE_BYTES + 1

View on GitHub (pinned to d540b00184)

Solutions

Replace the symlink/special file with a real regular file containing the oracle bytes.
Point the 'source' declaration at an actual regular file in the oracle root.
Re-materialize the oracle asset from its canonical source.

Defensive patterns

Strategy: type-guard

Validate before calling

import stat
from pathlib import Path

def assert_regular_file(root: Path, relative) -> None:
    p = root.joinpath(*Path(relative).parts)
    md = p.lstat()
    if stat.S_ISLNK(md.st_mode) or not stat.S_ISREG(md.st_mode):
        raise ValueError(f"{relative} must be a regular non-symlink file")

Type guard

def is_regular_non_symlink(root, relative) -> bool:
    import stat
    try:
        md = Path(root).joinpath(*Path(relative).parts).lstat()
    except OSError:
        return False
    return not stat.S_ISLNK(md.st_mode) and stat.S_ISREG(md.st_mode)

Try / catch

try:
    payload = _read_oracle_file(root, relative)
except ValueError as exc:
    if "bounded regular non-symlink" in str(exc):
        raise SystemExit(f"Replace symlink/special file at {relative} with a real file") from exc
    raise

Prevention

Never replace oracle source files with symlinks.
Audit oracle tree with `find <root> -type l -delete` after materializing.

When it happens

Trigger: The declared oracle source file is a symbolic link; it is a named pipe, socket, device, or directory rather than a regular file.

Common situations: An oracle file was replaced with a symlink for convenience; the path points at a FIFO or device node; the file was accidentally created as a directory.

Related errors

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