ErrLookup › Background articles › Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries

Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries

Config validation failed is the error family a tool raises when it parses your settings — pnpm-workspace.yaml, mise.toml, ruff --config, k6 script options, config.toml, or environment variables like RUSTFS_SCANNER_* — and rejects them before any real work runs. You meet it at startup, install, build, boot, or config-update time as messages like "invalid scanner config value for {key}: {value} ({reason})", "timeoutMs must be a positive integer", or "Failed to validate drainer configuration". This article covers the mechanism shared by the 113 documented records: a validation pass that checks types, ranges, names, paths, cross-field invariants, and backend capability after parsing succeeds but before the tool commits to work.

Distilled from 113 documented records across 19 repositories.

Background

These errors come from a dedicated validation layer that sits between config parsing and real work. Parsing (serde, clap, TOML and JSON readers) succeeds first; a hand-written guard runs second. Hyperswitch calls conf.validate() after deserialization and panics via expect when a structural check fails; RustFS runs WebDavConfig::validate() and ObjectDataCacheConfig::validate() before the services start; mise checks bin and rename_exe options the moment they are read; openhuman validates agent-tier hierarchies at registry load; pnpm compiles exclude lists into a version policy before any install work runs. The shared philosophy is fail fast: mise refuses a whole firewall request when one rule is bad rather than write a partial ruleset, k6 aborts startup when cloud-required tags are missing because aggregation would be incomplete, and pnpm rejects a reserved registry alias at startup because the named-registry resolver runs last, so the alias would be silently shadowed anyway.

From the caller's side the family usually names the offender, but the surface and timing are library-specific. RustFS's scanner error interpolates the exact key, value, and reason; pnpm derives an INVALID_<KEY> code from the setting key and wraps the parser's message; k6 joins every problem into one bulleted report and exits with code 104; Chroma names the offending kwarg or non-mutable key. How it surfaces varies: a Rust panic (Hyperswitch), a process exit code (k6), an S3 InvalidArgument on every quota-checked write until stored JSON is repaired (RustFS quota), a boot-time bail (openhuman), a warning-and-skip (mise launchd agent names), or a deliberately generic message that omits detail because config errors can embed credentials (CodeWhale, whose --json path prints the redacted diagnostic instead). A few validators run at update time rather than startup: Chroma's BM25 function rejects config updates outside its six mutable keys, and RustFS re-parses persisted quota JSON on every admission check.

The guards protect invariants that later layers silently assume. mise's safe-relative-path and plain-file-name checks keep resolved binaries inside the install directory; RustFS rejects zero WebDAV caps because an unbounded accept loop is a resource-exhaustion hole, and rejects identity_keys_max == 1 because the identity index would evict the previous key on every fill and thrash; charset limits exist because rule and agent names become stable identifiers in iptables/nftables rules and launchd labels; Neon rejects a (resource_multiplier, spread_factor) pair whose product with (spread_factor + 1.0) reaches 1.0 because the cache-sizing formula becomes unsolvable; Chroma requires kwargs to be JSON primitives because configs must round-trip through serialization. Grammars are strict on purpose too: pnpm's exclude patterns accept bare names, name globs, and exact versions or version unions, and reject semver ranges and glob-with-version combinations by design.

Two cautions from the records. Detail availability differs by library: most messages pinpoint the field, but CodeWhale's text path intentionally discards the underlying error, and the fix is to re-run codewhale doctor --json for the redacted, actionable diagnostic. And at least one documented raise site is dead code: Chroma's 'not a valid hnsw config' wraps typing.cast, which never raises at runtime, so that specific error cannot actually fire — treat any hnsw config failure as coming from somewhere else, or from real validation added in a fork.

Common causes

What usually fixes it

Go deeper

Documented occurrences

…and 93 more across the corpus — use search.

Honest provenance: generated on 2026-08-18 from AI-assisted analysis of the linked records. See how records are made.