ErrLookup › Background articles › IllegalArgumentException: When a Java Library Rejects the Argument You Handed It

IllegalArgumentException: When a Java Library Rejects the Argument You Handed It

IllegalArgumentException is the unchecked RuntimeException Java libraries throw when a method receives an argument that is the wrong value, wrong type, wrong shape, or wrong count. Developers meet it at trust boundaries — configuration parsing, script compilation, generic-type construction, reflection-backed bean wiring — wherever a library chooses to fail fast on bad input instead of carrying it forward into a confusing later failure. Across the 658 records in this family it is rarely a bug in the library; it is almost always the caller handing it something its contract never agreed to accept.

Distilled from 658 documented records across 8 repositories.

Background

IllegalArgumentException lives in java.lang and extends RuntimeException, so it is unchecked: a library is not obliged to declare it, and the caller is not obliged to catch it. It exists for the case where a method's signature admits a value but the method's contract does not — the type checks, but the value, count, or structure is unacceptable. The records in this family show that Java libraries reach for it as a deliberate fail-fast guard. Elasticsearch throws it at configuration validation time before a node boots (prohibited telemetry keys, unknown secure-settings source); Spring Framework throws it during BeanFactory initialization before context refresh completes (missing targetField, a singleton bean declared with a per-object aspect clause); Gson throws it inside TypeToken.getParameterized before a malformed ParameterizedType is ever built; and the Painless scripting engine throws it at compile time rather than emitting broken bytecode for an unresolvable method or constructor reference. The shared instinct is identical: reject early, name the offending value, and stop.

From the caller's side the exception almost always carries the bad value in its message — the prohibited config key, the class name lacking a reflection-reachable constructor, the mismatched type-argument count, or the expected-versus-found SHA-256 digests of a patched JAR. Because it is unchecked, it surfaces wherever the library happens to be when validation runs: at application startup for configuration and bean wiring, at the first script execution for Painless, or mid-deserialization for a Jackson forward reference. There is no single predictable layer to catch it at; it fires at the boundary where the caller's input first crosses into the library's internals. Several records note a secondary, harder guard behind it — an assert enabled only with -ea, or a defensive duplicate throw that should be unreachable if validation and parsing stay in sync — so the IAE is usually the first and loudest line, not the only one. The trigger surface is library-specific, and the records disagree enough that no single rule covers all of them. Elasticsearch leans on hardcoded allowlists — permitted telemetry.agent keys, whitelisted Painless methods, constructors and functional interfaces, recognized secure-settings sources, supported date-object getters — so the dominant Elasticsearch shape is 'your value is not on the list.' Spring Framework uses IllegalArgumentException for structural contract checks during AOP and FactoryBean setup: an aspect must carry @Aspect, a per-object aspect must be prototype-scoped, and a custom service-locator exception must expose a (String, Throwable) constructor reflection can reach. Gson and Jackson use it to police generic and identity invariants — type-argument arity, owner-type requirements of non-static inner classes, unresolved forward references, and ambiguous Map-key creators. A smaller set of records uses it as a low-level precondition where a wrong argument would corrupt native state: a vector pitch that is smaller than the row length, or a Lucene Directory that is not filesystem-backed when the GPU codec needs a real file path. One exception family, four very different trigger surfaces.

Common causes

What usually fixes it

Go deeper

Documented occurrences

…and 638 more across the corpus — use search.

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