Why Your Linter Misses the Bug: The Type System Gap Behind Runtime Crashes
Archi4 min read
Contents
The Bug Was Legal Code#
A service accepts a JSON payload, validates three fields, and writes to a database. Two weeks later a support ticket arrives: one field was null when the schema expected a string. The stack trace points at a line that type checking passed, linting passed, and code review approved. Every tool in the pipeline said the code was fine, and the code was fine in the sense that it compiled. The bug lived in a gap between what the type system could express and what the program actually assumed.
This is the root cause behind a large share of runtime failures in typed languages, and it is the reason adding another lint rule rarely helps. Linters pattern-match syntax. They do not know what your types mean.
Types Are Assertions the Compiler Cannot Check#
A static type system proves a narrow set of properties: function signatures line up, fields exist, nullability is handled where the language tracks it. It does not know that age must be non-negative, that email must contain an @, or that status has exactly four legal values that correspond to database rows.
In languages with structural typing (TypeScript being the obvious case), the gap widens. A value fetched from an API and cast to an interface satisfies the compiler without any runtime evidence. TypeScript erases at build time. The interface is a comment that happens to be machine-readable, and as is an instruction to stop asking questions.
ts interface User { id: string; plan: "free" | "pro" } const user = JSON.parse(body) as User; // compiler is satisfied
If the server sends plan: "enterprise", nothing complains until a switch statement hits its default branch at 2 a.m. The type was a promise the runtime never made.
The Three Places the Gap Opens#
- Trust boundaries. Data crossing a network, disk, or process boundary arrives untyped. Parsing libraries (zod, io-ts, pydantic, serde) close this gap, but only if the parsed value is what the rest of the code sees. Too often the validated object is discarded and the raw payload flows onward.
- Nullability that languages do not model. Go's zero values, Java's historical nulls, and Python's
Noneall allow a variable to hold a value the surrounding logic did not anticipate. Optional types help when the language enforces them. When it does not, you get the classic nil dereference. - State machines expressed as booleans. An order is
isPaid,isShipped,isCancelled. Three booleans have eight combinations, and at least two are impossible by design but representable in code. Every impossible state is a latent branch nobody tested.
None of these are lint problems. A linter can flag a missing null check. It cannot tell you that your booleans encode a state machine with unreachable states.
What Actually Closes the Gap#
Make illegal states unrepresentable. Replace parallel booleans with a tagged union or sealed class. An order is Pending | Paid | Shipped | Cancelled, and each variant carries only the fields that variant can have. The compiler then rejects the impossible combinations, and the switch statement becomes exhaustive-checked in TypeScript, Rust, and Kotlin.
ts type Order = | { kind: "pending" } | { kind: "paid"; paidAt: Date } | { kind: "shipped"; tracking: string; paidAt: Date };
This is not cosmetic. It moves a class of bugs from runtime to compile time, and compile-time bugs are cheap.
Validate at the boundary, once. Parse untrusted input into a named type at the edge of the system. Everything downstream accepts only that type. If the parser is the sole constructor, the type's invariants hold for the whole program by construction. Pydantic and zod both support this pattern, and the discipline matters more than the library.
Prefer newtypes over primitives. A UserId and an OrderId are both strings. Swapping them is a bug the type checker will not catch if both are string. A one-line wrapper catches it everywhere, at zero runtime cost in most languages.
Test the boundary, not the middle. Unit tests on pure functions with valid inputs prove little about the failure you saw in production. Property-based tests and fuzzing on the parser catch malformed input that hand-written cases miss. Tools like Hypothesis and fast-check generate the inputs you did not think of.
The Opinion, Stated Plainly#
Most teams respond to a production crash by adding a lint rule, a test case for that exact input, and a checklist item. This treats symptoms. The underlying defect is usually a type that permitted a state the system could not handle. The durable fix is to narrow the type until the bad state cannot be constructed, then let the compiler enforce it across every call site at once.
That work is harder than adding a rule, and it is unglamorous. It also removes whole categories of future bugs rather than the one you just fixed. A linter tells you where you wrote something suspicious. A better type tells you what is possible. The second is worth more, and it is the part most teams skip.
Start with one module. Find the booleans that encode a lifecycle, the as casts at the network edge, and the primitives that should have names. Replace them, then run the compiler and see what breaks. The breakage is the list of assumptions you were carrying silently.
More articles