ErrLookup › Background articles › "is required", "must be set", "missing required field": configuration validation errors across open-source libraries

"is required", "must be set", "missing required field": configuration validation errors across open-source libraries

"is required" and "must have" config errors appear when a library validates its configuration at load or startup time and a mandatory field is absent or empty — from litellm guardrails missing a guardrail_name, to Vertex providers without a project_id, mise bootstrap files with no content, and Cilium BGP instances without a localASN. This article explains why these fail-fast checks exist, where they fire, and the general patterns for fixing them.

Distilled from 101 documented records across 36 repositories.

Background

This family covers errors thrown during configuration validation: a library inspects a settings object — a YAML/JSON/TOML file, environment variables, a code-level config struct, or an API request body — and refuses to proceed because a field it considers mandatory is missing, null, empty, or whitespace-only. Unlike runtime failures, these errors usually fire before any real work happens: at startup, at config parse time, or in a validate() call. litellm aborts proxy startup when a guardrail entry lacks guardrail_name; gradle rejects an empty trusted-artifact entry while building verification metadata; mise rejects a bootstrap file entry during from_toml; caveman's objectstore.validateConfig runs inside FromEnv. The validation is deliberate: the library could theoretically continue (and fail later, less clearly), but instead it fails fast with a message naming the offending field.

Why the fields are mandatory varies. Some are needed to construct a value: the Vertex partner endpoint URL embeds the GCP project ID in its path, so 9router's VertexExecutor cannot build a URL at all without one. Some are needed for identity and routing: litellm's guardrail_name is the key used for mode matching, request-level guardrail selection, and logging, so a nameless guardrail cannot be registered. Some are needed to deserialize anything: Cilium's kvstore requires a KeyCreator function to instantiate typed keys during watch operations, and chroma's buildFromConfig cannot reconstruct a Qwen embedding function without model and task. Some simply guard against useless no-ops: zeroclaw's MQTT channel with zero topics would connect and receive nothing, and an empty Gradle trusted-artifact entry would silently disable dependency verification for everything.

From the caller's side, the error usually appears immediately after a config change — adding a new receiver, guardrail, provider, or channel — or after an upgrade, when a stored or generated config predates a required field (chroma collections persisted by older versions, mastra registries saved before servers_url existed). The messages are typically literal: fluentd names the missing key (host and port), mise lists the exact scheduling keys a timer unit must set, oh-my-pi enumerates every acceptable field an empty provider stanza could have set. Most libraries include the offending value's name — provider, model, instance, or guardrail — in the message.

Across the 36 repositories the family varies mainly in strictness and indirection. Some validators check only shape (caveman validates endpoint and bucket are non-empty after trimming; gradle needs one of four filter attributes, not all). Others cross-reference fields: oh-my-pi accepts api at either the provider or model level and exempts proxy-type discovery; 9router tries automatic project-ID resolution from the API key before giving up; mise reclassifies entries (a systemd entry with timer metadata but no schedule is rejected, while the same keys without any timer metadata would classify as a plain service). Defaults interact with validation in surprising ways: mise file entries default to state "present" and therefore require a body even when the author only wrote metadata keys; zeroclaw's topics key has an empty-vec default, so omitting it fails validation rather than silently subscribing to nothing. Whether whitespace-only values count as missing is also library-specific — caveman trims and rejects them, and crush rejects SSE URLs that resolve via shell variables to empty strings.

Common causes

What usually fixes it

Documented occurrences

…and 81 more across the corpus — use search.

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