t8y2/dbx · error · FileNotFoundError

{path}

Error message

{path}

What it means

required_path() reads a mandatory environment variable and resolves it to a Path. It raises ValueError when the variable is unset/empty, and FileNotFoundError when the path does not point to an existing file. This fails fast so benchmark configuration problems surface before any work is done.

Source

Thrown at agents/drivers/hive-go/bench/agent_compare.py:621

def percentile(values: list[float], fraction: float) -> float:
    if not values:
        return 0.0
    index = min(len(values) - 1, max(0, round((len(values) - 1) * fraction)))
    return values[index]


def elapsed_ms(started: float) -> float:
    return (time.perf_counter() - started) * 1000


def required_path(name: str) -> Path:
    value = os.getenv(name, "")
    if not value:
        raise ValueError(f"{name} is required")
    path = Path(value).expanduser().resolve()
    if not path.is_file():
        raise FileNotFoundError(path)
    return path


def env_default(name: str, fallback: str) -> str:
    return os.getenv(name, "") or fallback


def env_int(name: str, fallback: int) -> int:
    value = int(env_default(name, str(fallback)))
    if value < 1:
        raise ValueError(f"{name} must be positive")
    return value


def env_int_list(name: str, fallback: list[int]) -> list[int]:
    raw = os.getenv(name, "")
    values = fallback if not raw else [int(value.strip()) for value in raw.split(",")]
    if not values or any(value < 1 for value in values):

View on GitHub (pinned to c0390bff16)

Solutions

1. Export the required environment variable with a valid value before running (e.g. export NAME=/path/to/file)
2. Verify the variable name spelling matches what agent_compare.py expects
3. Check that the path exists and is a regular file (not a directory): ls -l "$NAME"
4. If the variable is optional now, switch the call site to env_default(name, fallback) instead of required_path

Example fix

// before
$ python agent_compare.py   # ValueError: HIVE_CONFIG is required
// after
$ export HIVE_CONFIG=./configs/agents.json
$ python agent_compare.py

import os
from pathlib import Path

def ensure_required_file_env(name: str) -> Path:
    value = os.getenv(name, "")
    if not value:
        raise SystemExit(f"Set {name} before running")
    path = Path(value).expanduser().resolve()
    if not path.is_file():
        raise SystemExit(f"{name}={value} is not an existing file")
    return path

config = ensure_required_file_env("HIVE_CONFIG")

def has_valid_path_env(name: str) -> bool:
    value = os.getenv(name, "")
    return bool(value) and Path(value).expanduser().is_file()

try:
    config = required_path("HIVE_CONFIG")
except ValueError:
    sys.exit("HIVE_CONFIG env var is required")
except FileNotFoundError as e:
    sys.exit(f"HIVE_CONFIG points to missing file: {e}")

When it happens

Trigger: os.getenv(name, "") returns "" because the env var (e.g. HIVE_AGENT_* path vars consumed by configured_candidates) is not exported or is exported empty; called from configured_candidates via main at startup.

Common situations: Running bench/agent_compare.py without sourcing an env file; a CI job missing a secret/env mapping; a typo in the variable name; pointing the var at a directory or nonexistent file instead of a regular file.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• {name} must be a boolean
• BENCH_CANDIDATES selected no candidates
• {name} is required
• {path}
• {name} must be positive

AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05). Data as JSON: /api/errors/1a10d5119c073be5. Report an issue: GitHub.