abhigyanpatwari/GitNexus · error · ValueError

task {task_id} oracle file {index} requires exactly source a

Error message

task {task_id} oracle file {index} requires exactly source and target

What it means

Raised inside the per-file loop of validate_oracle_declaration when one entry of oracle['files'] is not a dict whose key set is exactly {"source", "target"}. Each oracle file declaration pairs a harness-relative 'source' path with a worktree-relative 'target' path; extra or missing keys on any single entry are rejected, and the message includes the entry index for easy location.

Source

Thrown at eval/workflow_bench/oracle_assets.py:105

    oracle = task.get("oracle")
    if not isinstance(oracle, dict) or set(oracle) != {"command", "files"}:
        raise ValueError(f"task {task_id} oracle requires exactly command and files")
    command = oracle.get("command")
    if (
        not isinstance(command, str)
        or not command.strip()
        or len(command.encode()) > MAX_ORACLE_COMMAND_BYTES
        or "\x00" in command
    ):
        raise ValueError(f"task {task_id} oracle command must be nonblank and bounded")
    files = oracle.get("files")
    if not isinstance(files, list) or not files or len(files) > MAX_ORACLE_FILES:
        raise ValueError(f"task {task_id} oracle files must contain 1..{MAX_ORACLE_FILES} entries")
    sources: set[str] = set()
    targets: set[str] = set()
    for index, declaration in enumerate(files):
        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:

View on GitHub (pinned to d540b00184)

Solutions

Shape every files entry as exactly {"source": <relpath>, "target": <relpath>}.
Use the reported index to find the offending entry (0-based).
Remove any unsupported keys; if you need checksum/mode semantics, they are computed by the harness, not declared.

Example fix

// before
{"source": "a.txt", "dest": "a.txt"}
// after
{"source": "a.txt", "target": "a.txt"}

Defensive patterns

Strategy: type-guard

Validate before calling

for i, decl in enumerate(task["oracle"]["files"]):
    if not isinstance(decl, dict) or set(decl) != {"source", "target"}:
        raise ValueError(f"file entry {i} must be a dict with exactly source and target")

Type guard

def is_valid_file_declaration(decl) -> bool:
    return isinstance(decl, dict) and set(decl) == {"source", "target"}

Try / catch

try:
    validate_oracle_declaration(task)
except ValueError as exc:
    print(f"Bad oracle file declaration: {exc}")

Prevention

Use a typed dataclass or TypedDict to author file declarations.
Lint task fixtures with a schema validator (e.g. jsonschema) before capture.

When it happens

Trigger: A files entry that is a plain string instead of a dict; a dict missing 'source' or 'target'; a dict with an extra key like 'mode' or 'checksum'; a typo such as 'src'/'dest'.

Common situations: Hand-writing file declarations and using inconsistent key names across entries; copy-pasting a different schema (e.g. {'path': ...}); adding an unsupported field expecting the harness to honor it.

Related errors

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