{"record":{"id":"1a10d5119c073be5","repo":"t8y2/dbx","slug":"path-1a10d5","errorCode":null,"errorMessage":"{path}","messagePattern":"\\{path\\}","errorType":"exception","errorClass":"FileNotFoundError","httpStatus":null,"severity":"error","filePath":"agents/drivers/hive-go/bench/agent_compare.py","lineNumber":621,"sourceCode":"\ndef percentile(values: list[float], fraction: float) -> float:\n    if not values:\n        return 0.0\n    index = min(len(values) - 1, max(0, round((len(values) - 1) * fraction)))\n    return values[index]\n\n\ndef elapsed_ms(started: float) -> float:\n    return (time.perf_counter() - started) * 1000\n\n\ndef required_path(name: str) -> Path:\n    value = os.getenv(name, \"\")\n    if not value:\n        raise ValueError(f\"{name} is required\")\n    path = Path(value).expanduser().resolve()\n    if not path.is_file():\n        raise FileNotFoundError(path)\n    return path\n\n\ndef env_default(name: str, fallback: str) -> str:\n    return os.getenv(name, \"\") or fallback\n\n\ndef env_int(name: str, fallback: int) -> int:\n    value = int(env_default(name, str(fallback)))\n    if value < 1:\n        raise ValueError(f\"{name} must be positive\")\n    return value\n\n\ndef env_int_list(name: str, fallback: list[int]) -> list[int]:\n    raw = os.getenv(name, \"\")\n    values = fallback if not raw else [int(value.strip()) for value in raw.split(\",\")]\n    if not values or any(value < 1 for value in values):","sourceCodeStart":603,"sourceCodeEnd":639,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/hive-go/bench/agent_compare.py#L603-L639","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Export the required environment variable with a valid value before running (e.g. export NAME=/path/to/file)","Verify the variable name spelling matches what agent_compare.py expects","Check that the path exists and is a regular file (not a directory): ls -l \"$NAME\"","If the variable is optional now, switch the call site to env_default(name, fallback) instead of required_path"],"exampleFix":"// before\n$ python agent_compare.py   # ValueError: HIVE_CONFIG is required\n// after\n$ export HIVE_CONFIG=./configs/agents.json\n$ python agent_compare.py","handlingStrategy":"validation","validationCode":"import os\nfrom pathlib import Path\n\ndef ensure_required_file_env(name: str) -> Path:\n    value = os.getenv(name, \"\")\n    if not value:\n        raise SystemExit(f\"Set {name} before running\")\n    path = Path(value).expanduser().resolve()\n    if not path.is_file():\n        raise SystemExit(f\"{name}={value} is not an existing file\")\n    return path\n\nconfig = ensure_required_file_env(\"HIVE_CONFIG\")","typeGuard":"def has_valid_path_env(name: str) -> bool:\n    value = os.getenv(name, \"\")\n    return bool(value) and Path(value).expanduser().is_file()","tryCatchPattern":"try:\n    config = required_path(\"HIVE_CONFIG\")\nexcept ValueError:\n    sys.exit(\"HIVE_CONFIG env var is required\")\nexcept FileNotFoundError as e:\n    sys.exit(f\"HIVE_CONFIG points to missing file: {e}\")","preventionTips":["Use a .env file loaded at startup and committed as .env.example documenting every required var","Add a preflight check in CI that all required env vars are set and paths exist","Fail fast at program start by calling all required_path checks before doing work","Echo resolved paths in a dry-run mode to catch typos early"],"tags":["environment","configuration","path-validation","python"],"backgroundTag":"missing-env-var","analyzedSha":"c0390bff16418b651f4728520d99adf8ce48829a","analyzedAt":"2026-09-05T23:05:10.900Z","contentChangedAt":"2026-09-05T23:05:10.900Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}