ErrLookup › Background articles › "must be positive", "Invalid value": how libraries reject invalid parameter values (ValueError, ArgumentError, INVALID_PARAMETER_VALUE)

"must be positive", "Invalid value": how libraries reject invalid parameter values (ValueError, ArgumentError, INVALID_PARAMETER_VALUE)

"must be positive", "Invalid task", "Unsupported action", "Invalid recurse value", and "INVALID_PARAMETER_VALUE" are all faces of the same error family: a library checked a parameter you passed against its allowed set or range and refused it before doing any work. These fail-fast validation errors appear at construction, config-load, or API-dispatch time across matplotlib, MLflow, Chroma, LiteLLM, Puppet, and many others. This article explains why libraries validate eagerly, the recurring trigger patterns (zero used as a sentinel, wrong vocabulary, case and whitespace mismatches, data-derived values that drift to zero), and how to fix and prevent them.

Distilled from 127 documented records across 28 repositories.

Background

This family lives at the boundary between caller and library. Somewhere between accepting your argument and starting real work, the library runs a check: is this value in the allowed set, in the allowed range, or of the allowed shape? If not, it raises immediately — a Python ValueError or MlflowException with INVALID_PARAMETER_VALUE, a Ruby ArgumentError or Puppet::Error, a TypeScript ApiError with status 400, or a plain language-specific Exception. The defining trait is eagerness: the error fires at construction or dispatch time (constructing a RateLimiter with requests_per_second=0, entering a wan_memory_optimization context, calling set_xscale) or at request-parse time (parsePrintOptions rejecting a bad orientation or kind), not deep inside the operation. MLflow's docs for diffusers.save_model state the rationale plainly: fail fast so you don't get an unusable config that only blows up later at load or inference time.

Why the checks exist varies by mechanism. Some parameters are mathematically degenerate at invalid values: matplotlib's symlog linscale and asinh linear_width collapse or invert their transforms at zero, a token-bucket rate limiter with a non-positive refill rate never refills, and a chunking helper with a non-positive limit would loop forever — so the guard is a theorem, not a style choice. Others are whitelists: Danbooru's period param accepts exactly eight singular granularities, OpenProject's hierarchy endpoint accepts exactly 'parent' or 'child', Hiera's merge option accepts a fixed set of strings, LiteLLM's Nova Canvas builder knows four task types. Here the error is a vocabulary mismatch — you used a word from a neighboring API (tidy's recurse doesn't accept file's 'remote'; Chroma's HF sparse EF doesn't accept Nomic's 'search_document' task names). A third shape is structural: zeroclaw's checkout requires the branch to sanitize to exactly one token, MLflow's dataset constructor names must start with 'load_' or 'from_', and evaluate() with predictions requires dataframe-like data because named columns are meaningless for arrays.

From the caller's side, these errors usually mean one of a handful of situations. Zero or a non-positive number was used where only strictly positive values are valid — often because 0 was intended to mean 'disabled' or 'no limit', a convention most of these APIs explicitly do not honor (use enabled=False, omit the parameter, or use a different mode instead). A value computed from data or config drifted to an edge case: a linear_width computed from a constant signal is exactly 0, len(endpoints) * base_rps evaluates to 0, a computed chunk limit goes negative after subtracting a header. Or a string value is subtly wrong: wrong case ('LandScape', 'PDF'), a plural ('days' instead of 'day'), a synonym ('jpg' instead of 'jpeg'), a trailing space, a hyphen where an underscore belongs ('request-review' vs 'request_review'), or a symbol where a string is expected (Puppet's :true vs 'true').

The family varies across libraries mainly in error surface and strictness. Python libraries tend toward ValueError or a typed MlflowException carrying an INVALID_PARAMETER_VALUE code; web backends return 400 with the bad value interpolated into the message; older or plainer codebases raise bare Exceptions with a formatted string. Strictness also differs: matplotlib's bw_method matches 'scott' case-insensitively, while most string whitelists are exact and case-sensitive. Some checks sit behind type hints that don't actually enforce anything at runtime — Chroma's task parameter is typed as a Literal but an invalid value surfaces only on the first add/query — which is why the same family can appear as a confusingly late error rather than an immediate one.

Common causes

What usually fixes it

Go deeper

Documented occurrences

…and 107 more across the corpus — use search.

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