t8y2/dbx · error · ValueError

{name} must be a boolean

Error message

{name} must be a boolean

What it means

env_bool parses a boolean environment variable from a restricted set of literals ('1','true','yes','on' vs '0','false','no','off', case-insensitive) and raises ValueError for anything else. The harness deliberately rejects ambiguous spellings like 'True ', 'TRUE', 'enabled', 'y', or '1.0' so behavior is deterministic. Empty/unset falls back to the default, so the error only occurs when the variable is set to an unrecognized string.

Source

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

def env_float(name: str, fallback: float) -> float:
    value = float(env_default(name, str(fallback)))
    if value <= 0:
        raise ValueError(f"{name} must be positive")
    return value


def env_bool(name: str, fallback: bool) -> bool:
    raw = os.getenv(name)
    if raw is None or raw == "":
        return fallback
    normalized = raw.strip().lower()
    if normalized in {"1", "true", "yes", "on"}:
        return True
    if normalized in {"0", "false", "no", "off"}:
        return False
    raise ValueError(f"{name} must be a boolean")


if __name__ == "__main__":
    main()

View on GitHub (pinned to c0390bff16)

Solutions

1. Set the variable to one of 1, true, yes, on, 0, false, no, off (case-insensitive)
2. Unset or leave empty to use the default
3. Check for stray whitespace, quotes, or CR characters in your shell profile / CI config

Example fix

// before
export BENCH_VERBOSE=enabled
// after
export BENCH_VERBOSE=true

import os
ALLOWED_TRUE = {"1", "true", "yes", "on"}
ALLOWED_FALSE = {"0", "false", "no", "off"}
def validate_bool_env(name: str) -> None:
    raw = os.getenv(name)
    if raw and raw.strip().lower() not in ALLOWED_TRUE | ALLOWED_FALSE:
        raise SystemExit(f"{name} must be one of 1/true/yes/on/0/false/no/off")
validate_bool_env("BENCH_VERBOSE")

def is_bool_literal(raw: str | None) -> bool:
    return raw is not None and raw.strip().lower() in {"1","true","yes","on","0","false","no","off"}

try:
    run_bench()
except ValueError as e:
    if "must be a boolean" in str(e):
        print(f"Fix boolean env var: {e}"); sys.exit(2)
    raise

When it happens

Trigger: Setting an env var read by env_bool to a value outside {1,true,yes,on,0,false,no,off} after lowercasing and stripping whitespace, e.g. TRUE-ish words like 'enable', 'y', '2', or trailing punctuation.

Common situations: Copy-pasting 'TRUE' with a trailing quote or space from docs; using 'yes' vs 'ja' style values; scripts exporting "$(flag)" where the variable is empty-with-quotes or holds 'on/off' variants the parser doesn't know; mixing conventions with other tools that accept arbitrary truthy strings.

Understand the failure class

Background: "is not a valid" / "Invalid ... value" environment variable errors: how libraries validate env vars and what to do when they reject yours — this error's family across 48 libraries.

Related errors

• {name} must be a boolean
• BENCH_CANDIDATES selected no candidates
• {name} is required
• BENCH_CANDIDATES selected no candidates
• {name} is required

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