ErrLookup › Background articles › Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries

Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries

"Type mismatch" errors fire when a value's runtime type doesn't fit what an API, converter or codec declared: from IllegalArgumentException and TypeError to custom guards like FlowableIllegalArgumentException. This article explains where the check lives, why it fires, and how 2,292 records across 150 libraries handle it.

Distilled from 2,292 documented records across 150 repositories.

Background

This family collects 2,292 documented records from 150 repositories, and its shape varies less by language than by where the type check sits. At one end are eager, fail-fast guards thrown at API boundaries: spring-projects/spring-ai rejects an @McpLogging callback whose second parameter is not String at registration time, java-native-access/jna refuses callback parameters that have no native mapping, and apple/pkl raises a type mismatch when a value's class is not a subclass of the module or this type. At the other end are checks deep in decoding paths: SeaQL/sea-orm panics in its PostgreSQL row-decoding when a TIMESTAMP column cannot be decoded as NaiveDateTime, bytebase/bytebase wraps a "failed to scan" error when a row column cannot be scanned into the destination Go variables, and apache/cassandra's collection codecs catch an internal cast failure and rethrow it as InvalidTypeException naming the CQL type, the expected Java class and the actual one.

The exception classes show how libraries layer their own names on top of the platform ones. IllegalArgumentException leads with 271 uses, but flowable/flowable-engine throws FlowableIllegalArgumentException 97 times and Activiti/Activiti throws ActivitiIllegalArgumentException 52 times, each keeping the family recognizable while adding project context. TypeError (60 uses) dominates the Python and JavaScript side: lancedb/lancedb fails when an OpenCLIP query is neither a str nor a PIL Image, and cocoindex-io/cocoindex raises a TypeError when a memo_key transform returns anything but a dict. Downcast-style checks appear too, like spring-security's ClassCastException when an @AuthenticationPrincipal does not match the declared parameter type, and dotnet/machinelearning's InvalidOperationException when a tokenizer is not an EnglishRobertaTokenizer.

From the caller's side, the message is usually the diagnostic: apache/seatunnel names both the actual Java class received and the target column type, Activiti names the field, the declared value type and the expected one, and puppetlabs/puppet's TypeAsserter builds expected-versus-actual descriptions including nested mismatches. Handling across the corpus is dominated by checking before it fires: 1,264 records use type-guards and 879 use validation, against only 136 try-catch and 13 fallback. That skews the practical advice toward coercing inputs before the call rather than catching afterwards.

Severity is almost uniformly error (2,238 of 2,292), with a small warning band like risingwavelabs/risingwave, which logs a warning and silently skips a Turbopuffer row whose primary key type cannot become a document id. Every record in the family now has at least one recorded solution, so the pages are actionable; what differs per library is whether the mismatch is a programming bug to fix at the call site, a schema or wire-format drift to reconcile, or a dropped-data situation to monitor.

Common causes

What usually fixes it

Documented occurrences

…and 2,272 more across the corpus — use search.

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