ErrLookup › Background articles › Invalid option value errors: "must be one of", "is not a valid", and "only allows" failures explained

Invalid option value errors: "must be one of", "is not a valid", and "only allows" failures explained

"Invalid option value" errors — messages like "must be one of [SKIP, FAIL]", "is not a valid type", "only allows '.', '-' and alphanumeric characters", or "invalid ... value" — fire when a library rejects a configuration or call option that falls outside its hard-coded vocabulary. Developers meet this family at generator, parser, test-framework, and CLI boundaries: the value is checked eagerly before any real work starts, and the fix is almost always correcting the value to the library's exact accepted set rather than working around the check.

Distilled from 78 documented records across 23 repositories.

Background

This family lives at the trust boundary between caller and library. When a library exposes an option, it usually has a closed vocabulary — an enum, a whitelist of symbols, a regex over strings, or a numeric range — and it validates eagerly: the check runs during option parsing, query construction, or builder setup, before rendering, generation, network work, or test execution begins. That is why these errors feel abrupt: nothing partial has happened yet, and re-running with a corrected value is safe. The producing layer varies (a Java generator's processOpts, a Ruby gem's DSL evaluation, a TypeScript builder synchronously assembling a tool definition), but the caller-side shape is the same: an exception naming the offending value, often with the supported list appended.

The mechanism splits into three sub-shapes across the family. Enum membership is the most common: openapi-generator parsing declarativeInterfaceReactiveMode with a case-sensitive valueOf() that knows exactly coroutines and reactor; Capybara accepting only :all and :visible for text queries; Bundler matching --trust-policy against CamelCase RubyGems security policy names. Shape validation covers numeric guards — caveman requiring safe positive integers for token wallets and timeouts, Angular rejecting timeout values below 1 or non-integers because the platform would silently drop them — and character-set regexes like openapi-generator's suffix options, where dots and dashes are fine in file names but forbidden in class names. Vocabulary confusion is a recurring trigger inside the mechanism: GNU cp --preserve words pasted into Hadoop's -p letters, Playwright's polling: 'interval' passed to k6, and 0.x option symbols carried into a 2.x API with a smaller whitelist all fail because two tools share a concept but not a vocabulary.

Comparison is typically exact. Case matters in openapi-generator's valueOf parses and Vagrant's tgz/zip list, though some libraries normalize by trimming and upper-casing before matching. Messages vary in helpfulness: many append the full supported set (Bundler, brakeman, openapi-generator's enum lists), while others — like openapi-generator's Xojo "invalid enum property naming option" text that actually refers to the serialization library — carry copy-paste artifacts or misleading labels (the server generator's apiFileSuffix reported as 'Service'). A recurring trap is that sentinel values often do not exist: NONE is invalid for optionalNonNullPropertyJsonSetterNulls, 0 does not mean 'disabled' for timeouts or compaction knobs, and the documented disable path is omitting the option entirely, which is library-specific behavior worth checking per record.

Common causes

What usually fixes it

Go deeper

Documented occurrences

…and 58 more across the corpus — use search.

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