t8y2/dbx · error · ValueError

{name} is required

Error message

{name} is required

What it means

required_path reads an environment variable holding a file path and raises ValueError if it is empty/unset, before even checking existence. It is used for mandatory inputs like candidate artifacts (agent binaries, JDBC jar).

Source

Thrown at agents/drivers/argo-go/bench/agent_compare.py:618

    shift = offset % len(values)
    return values[shift:] + values[:shift]


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]:

View on GitHub (pinned to c0390bff16)

Solutions

1. Export the required variable, e.g. `export ARGO_GO_AGENT=/path/to/agent-binary` before running
2. Source the env file / CI secrets that define the artifact paths
3. Check the configured_candidates call sites for the exact variable names required for the selected BENCH_CANDIDATES
4. Wrap the run in a preflight script that checks all required vars and fails early with a clear message

Example fix

// before
python3 agent_compare.py  # ValueError: ARGO_GO_AGENT is required
// after
export ARGO_GO_AGENT=$PWD/agents/drivers/argo-go/bin/agent
python3 agent_compare.py

import os
for var in ("ARGO_GO_AGENT", "JDBC_JAR"):
    if not os.getenv(var):
        raise SystemExit(f"{var} is required; export it before running")

try:
    jar = required_path("JDBC_JAR")
except ValueError as e:
    sys.exit(f"missing config: {e}")
except FileNotFoundError as e:
    sys.exit(f"path does not exist: {e}")

When it happens

Trigger: configured_candidates calls required_path("ARGO_GO_AGENT") or similar and the variable is not exported (or exported as empty string) in the shell running the bench.

Common situations: Running the bench from a fresh shell/CI job where env vars weren't sourced from .env; misspelled variable name; var defined in one terminal but not the one running the script.

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

• BENCH_CANDIDATES selected no candidates
• {path}
• {name} must be positive
• {name} must contain positive integers
• {name} is required

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