t8y2/dbx · error · ValueError

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.

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

• BENCH_CANDIDATES selected no candidates
• is required
• must be a boolean
• BENCH_CANDIDATES selected no candidates
• Missing version for native driver

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

Appendix: 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)