{"record":{"id":"0bf2f5f108bdf042","repo":"t8y2/dbx","slug":"name-is-required-0bf2f5","errorCode":null,"errorMessage":"{name} is required","messagePattern":"(.+?) is required","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"agents/drivers/hive-go/bench/agent_compare.py","lineNumber":618,"sourceCode":"    shift = offset % len(values)\n    return values[shift:] + values[:shift]\n\n\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]:","sourceCodeStart":600,"sourceCodeEnd":636,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/hive-go/bench/agent_compare.py#L600-L636","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set the named variable to an absolute path of an existing file, e.g. export AGENT_JAR=/path/to/agent.jar","Build/download the missing artifact first, then rerun","Verify the path points to a file (not a directory) and is readable","Run the bench from a working directory where the relative path resolves correctly"],"exampleFix":"// before\nexport HIVE_AGENT_BIN=\n// after\nexport HIVE_AGENT_BIN=/opt/bench/bin/hive-go-agent","handlingStrategy":"validation","validationCode":"import os\nfrom pathlib import Path\ndef preflight_required_path(name: str) -> Path:\n    value = os.getenv(name, \"\")\n    if not value:\n        raise SystemExit(f\"{name} is required\")\n    p = Path(value).expanduser().resolve()\n    if not p.is_file():\n        raise SystemExit(f\"{name} does not point to a file: {p}\")\n    return p\npreflight_required_path(\"HIVE_AGENT_BIN\")","typeGuard":"def is_valid_path_env(name: str) -> bool:\n    value = os.getenv(name, \"\")\n    return bool(value) and Path(value).expanduser().is_file()","tryCatchPattern":"try:\n    candidates = configured_candidates()\nexcept ValueError as e:\n    if \"is required\" in str(e):\n        var = str(e).split(\" \")[0]\n        os.environ[var] = default_artifact_path(var)\n        candidates = configured_candidates()\n    raise","preventionTips":["Export required artifact paths in CI before the bench step","Build artifacts as an explicit prerequisite step and verify existence","Use absolute paths in config to avoid cwd sensitivity","Run a preflight script that checks all required env vars before long setup"],"tags":["python","environment-variables","missing-file","configuration"],"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-14T05:17:10.506Z"}