abhigyanpatwari/GitNexus · error · ValueError

oracle root is unavailable: {lexical}

Error message

oracle root is unavailable: {lexical}

What it means

Raised by _real_oracle_root when lstat() or resolve(strict=True) on the oracle root path raises OSError — meaning the path does not exist, is not reachable, or cannot be resolved. This is a harness-internal guard run by capture_task_oracle before reading any oracle file. The message echoes the lexical absolute path that failed.

Source

Thrown at eval/workflow_bench/oracle_assets.py:122

        if not isinstance(declaration, dict) or set(declaration) != {"source", "target"}:
            raise ValueError(f"task {task_id} oracle file {index} requires exactly source and target")
        source = _bounded_relative_path(declaration.get("source"), label=f"task {task_id} oracle source")
        target = _bounded_relative_path(declaration.get("target"), label=f"task {task_id} oracle target")
        if source.as_posix() in sources:
            raise ValueError(f"task {task_id} oracle source is duplicated: {source}")
        if target.as_posix() in targets:
            raise ValueError(f"task {task_id} oracle target is duplicated: {target}")
        sources.add(source.as_posix())
        targets.add(target.as_posix())


def _real_oracle_root(root: Path) -> Path:
    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:

View on GitHub (pinned to d540b00184)

Solutions

  1. Verify the oracle root directory exists: ensure eval/workflow_bench/oracles is present, or your GITNEXUS_BENCH_ORACLE_ROOT value is correct.
  2. Mount/copy the oracle assets directory into the runtime environment.
  3. If using a custom root, pass an existing absolute directory to capture_task_oracle(root=...).
  4. Check filesystem permissions allow lstat on every component of the path.
Defensive patterns

Strategy: try-catch

Validate before calling

from pathlib import Path
from eval.workflow_bench.oracle_assets import ORACLE_ROOT

def ensure_root(root: Path = ORACLE_ROOT) -> Path:
    lex = root.expanduser().absolute()
    if not lex.exists():
        raise FileNotFoundError(f"oracle root does not exist: {lex}")
    return lex

Type guard

def oracle_root_exists(root) -> bool:
    try:
        Path(root).expanduser().absolute().lstat()
        return True
    except OSError:
        return False

Try / catch

from pathlib import Path
try:
    snap = capture_task_oracle(task, root=root)
except ValueError as exc:
    if "oracle root is unavailable" in str(exc):
        raise SystemExit(f"Oracle root missing/inaccessible: {exc}") from exc
    raise

Prevention

When it happens

Trigger: Calling capture_task_oracle(task, root=<path>) where <path> does not exist; the default ORACLE_ROOT (eval/workflow_bench/oracles) is missing; the path is on an unmounted filesystem; permissions deny stat.

Common situations: Running the benchmark from a checkout that does not include the oracles directory; pointing GITNEXUS_BENCH_ORACLE_ROOT at a wrong or stale path; running in a container where the oracle volume is not mounted; the directory was deleted or never created.

Related errors

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