t8y2/dbx · error · ValueError

{name} is required

Error message

{name} is required

What it means

required_path reads an environment variable that must name an existing file and raises ValueError('{name} is required') when the variable is unset or empty. The bench requires artifacts (e.g. the JDBC agent JAR) and fails fast when they are not configured.

Source

Thrown at agents/drivers/cassandra-go/bench/agent_compare.py:290

        "ops_per_sec": workload["count"] / elapsed,
        "mean_ms": statistics.mean(samples),
        "p50_ms": percentile(ordered, 0.50),
        "p95_ms": percentile(ordered, 0.95),
        "p99_ms": percentile(ordered, 0.99),
    }


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 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_float(name: str, fallback: float) -> float:

View on GitHub (pinned to c0390bff16)

Solutions

1. Set the named variable to a path that exists, e.g. export JDBC_AGENT_JAR=/path/to/agent.jar
2. Ensure the variable is exported (not just a shell-local) in CI
3. Confirm the path points to a regular file (see FileNotFoundError variant if it exists but isn't a file)

Example fix

// before
JDBC_AGENT_JAR= python agent_compare.py
// after
JDBC_AGENT_JAR=./target/agent.jar python agent_compare.py

name = "JDBC_AGENT_JAR"
value = os.getenv(name, "")
if not value:
    raise SystemExit(f"{name} must be exported and point to the agent artifact")

try:
    candidates = configured_candidates()
except ValueError as exc:
    if "is required" in str(exc):
        sys.exit(f"missing required env var — {exc}")
    raise

When it happens

Trigger: A selection in BENCH_CANDIDATES (e.g. 'jdbc') requires JDBC_AGENT_JAR, but that env var is unset or empty when configured_candidates runs.

Common situations: New machine/CI runner without the artifact env vars; artifact variable defined but not exported; renamed variable after a script update.

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
• {path}
• {name} must be positive
• {path}

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