ErrLookup › Background articles › "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it

"Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it

Invalid config value errors — messages like "Invalid value '%{value}' for parameter", "allowed values are", "invalid bool value", "must be one of" — fire when a setting receives a value outside the fixed set, type, or range a library validates. Developers meet them at server boot (Puma, Hadoop), during bootstrap (Hibernate, Maven), on CLI runs and publishes (fluentd, deno publish), or at first use of a configured feature (Chroma, AFFiNE), most often from a typo, wrong case, stray whitespace, a wrong value type, or a value that was never valid in this version.

Distilled from 133 documented records across 41 repositories.

Background

Configuration reaches libraries as raw strings — XML property values, YAML, env vars, CLI flags — but internally the library wants an enum member, a positive integer, an object instance, or a member of a small allowlist. Nearly every library therefore puts a validation gate at the parse or configure boundary. Puppet settings run hook procs at config-parse time, Puma validates the IO selector backend while building its reactor at boot, Hibernate's ConfigurationHelper inspects setting types while assembling a SessionFactory or EntityManagerFactory, and fluentd validates parser type declarations during configure, before any data flows. This family is what that gate raises.

From the caller's side the errors are usually self-describing: Puppet prints the offending value and the full allowed list, matplotlib lists every supported value and even hints when quotes are part of the string, and Hibernate's int-coercion failure prints the setting name, the raw value, and the value's concrete class. Timing varies by library. Most validators run eagerly so a daemon fails before serving traffic, but some are lazy: flow-remove-types rejects a bad includes/excludes option only on the first require() of a JS file, openapi-generator checks mergeConflictStrategy only when mergeMode is DEEP (a bad value passes silently in REF mode), and chroma validates query_config only on the embed_query path. Passing startup is therefore not proof that a config is valid.

The rules themselves differ per library, so the same-looking value can pass one validator and fail another. Case handling is a common trap: fluentd accepts only lowercase true/false/yes/no, while Hibernate's TCCL precedence and Maven's reference types accept any case, and openapi-generator normalizes case but never trims whitespace — nor does Maven. Boolean spellings diverge too: hadoop-tos and fluentd reject 1/0, on/off, and YES because only the literal spellings pass. Even the failure mode varies: most libraries throw, but Maven warns and falls back to a default reference type, and siyuan's update-channel reader silently falls back to "stable" while only the setter is strict.

Bad values enter config through predictable channels: hand edits and copy-paste (smart quotes from documentation, quoted values in matplotlibrc or style files), env vars and templating (WEB_CONCURRENCY set to "two", trailing commas in comma-separated host lists, a generic FREQUENCY variable fed into an enum-valued setting), wholesale migration from older versions or other systems (Puppet 3 configs, legacy checksum names, the literal "after" Hibernate rejects), config-generation code that skips validation (duplicate entries in concatenated lists, blank map keys, empty list segments), and drift between client and server (AFFiNE CalDAV preset ids cached from an older server configuration).

Common causes

What usually fixes it

Go deeper

Documented occurrences

…and 113 more across the corpus — use search.

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