abhigyanpatwari/GitNexus · error · ValueError

oracle parent is unreadable: {relative}

Error message

oracle parent is unreadable: {relative}

What it means

Raised by _read_oracle_file when lstat() on an intermediate parent directory of an oracle source file raises OSError while walking the path components. This means a directory component of the declared source path does not exist or is inaccessible, so the harness cannot safely reach the oracle file.

Source

Thrown at eval/workflow_bench/oracle_assets.py:135

    lexical = root.expanduser().absolute()
    try:
        metadata = lexical.lstat()
        resolved = lexical.resolve(strict=True)
    except OSError as exc:
        raise ValueError(f"oracle root is unavailable: {lexical}") from exc
    if stat.S_ISLNK(metadata.st_mode) or not stat.S_ISDIR(metadata.st_mode) or resolved != lexical:
        raise ValueError(f"oracle root must be a real non-symlink directory: {lexical}")
    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)

View on GitHub (pinned to d540b00184)

Solutions

  1. Create the missing parent directories under the oracle root so the full source path is reachable.
  2. Correct the declared 'source' path to match the actual location of the oracle file.
  3. Fix directory permissions so the harness process can lstat each component.
Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path

def parents_exist(root: Path, relative) -> None:
    cur = root
    for part in Path(relative).parts[:-1]:
        cur /= part
        if not cur.exists():
            raise FileNotFoundError(f"missing oracle parent directory: {cur}")

Type guard

def oracle_parents_readable(root, relative) -> bool:
    import stat
    cur = Path(root)
    for part in Path(relative).parts[:-1]:
        cur /= part
        try:
            md = cur.lstat()
        except OSError:
            return False
        if stat.S_ISLNK(md.st_mode) or not stat.S_ISDIR(md.st_mode):
            return False
    return True

Try / catch

try:
    payload = _read_oracle_file(root, relative)
except ValueError as exc:
    if "parent is unreadable" in str(exc):
        raise SystemExit(f"Oracle source path has a missing parent: {relative}") from exc
    raise

Prevention

When it happens

Trigger: A declared oracle 'source' whose intermediate directories do not exist under the oracle root; a parent directory with permissions denying lstat; a path component that has been removed since declaration validation.

Common situations: Declaring source='a/b/c.txt' when 'a/b' does not exist in the oracle root; the oracle asset tree was partially deleted; permission mismatch on an intermediate directory; race where a parent dir disappears between validation and capture.

Related errors

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