t8y2/dbx · error · ValueError

{name} is required

Error message

{name} is required

What it means

required_path() reads a mandatory path-valued environment variable and raises ValueError when it is empty/unset, then FileNotFoundError if the resolved path isn't a file. configured_candidates() uses it to locate required artifacts (e.g. agent binaries/jars) before launching candidates.

Source

Thrown at agents/drivers/hive-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. Set the named variable to an absolute path of an existing file, e.g. export AGENT_JAR=/path/to/agent.jar
2. Build/download the missing artifact first, then rerun
3. Verify the path points to a file (not a directory) and is readable
4. Run the bench from a working directory where the relative path resolves correctly

Example fix

// before
export HIVE_AGENT_BIN=
// after
export HIVE_AGENT_BIN=/opt/bench/bin/hive-go-agent

import os
from pathlib import Path
def preflight_required_path(name: str) -> Path:
    value = os.getenv(name, "")
    if not value:
        raise SystemExit(f"{name} is required")
    p = Path(value).expanduser().resolve()
    if not p.is_file():
        raise SystemExit(f"{name} does not point to a file: {p}")
    return p
preflight_required_path("HIVE_AGENT_BIN")

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

try:
    candidates = configured_candidates()
except ValueError as e:
    if "is required" in str(e):
        var = str(e).split(" ")[0]
        os.environ[var] = default_artifact_path(var)
        candidates = configured_candidates()
    raise

When it happens

Trigger: Invoking the bench without setting an env var like an agent binary or JDBC jar path, or setting it to a path that doesn't exist / points to a directory instead of a file.

Common situations: Fresh CI machine missing the built artifact; wrong relative path since the script resolves against cwd; artifact moved after a rebuild; forgetting to export the variable in a new shell or before sudo.

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
• {name} must be a boolean
• BENCH_CANDIDATES selected no candidates

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