A project compiles cleanly against library X version 1.5, but after the build tool resolves a transitive version conflict, X version 2.0 ends up on the runtime classpath instead. At runtime, the code throws a NoSuchMethodError. Walk through why this happens even though nothing failed during compilation.

## Two distinct phases: compilation and linking To understand why this breaks at runtime instead of compile time, it helps to separate two distinct phases the JVM goes through: compilation and linking. 1. When `javac` compiles a call site like `x.someMethod(arg)`, it does not embed a copy of `someMethod`'s implementation into the calling class's bytecode. 2. Instead it embeds a **symbolic reference** — the target class's fully qualified name, the method name, and its descriptor (an encoding of parameter and return types) — into the **constant pool** of the caller's `.class` file. 3. That symbolic reference is only resolved to an actual method later, during **class linking**, which happens when the JVM loads and verifies the class at runtime, not during the original compile. Compilation therefore only proves "this method existed, with this exact signature, in the version of library X that was on the compile classpath at that moment." It says nothing about whatever version of X will actually be present when the program runs. ## Why the two-phase design exists This two-phase design exists because it's what makes **separate compilation** and **dynamic linking** possible at all: Java classes can be compiled independently and combined later, which is precisely what a build tool assembling a dependency graph is doing — merging together jars that were each compiled independently, at different times, against their own compile classpaths, potentially pointing at different versions of the same shared library. ## Walking the failure through this scenario In this scenario, the caller class was compiled against X 1.5, so its constant pool holds a symbolic reference matching X 1.5's exact signature for that method. If the dependency resolver later decides the single X jar that ships with the application is 2.0, and 2.0 changed it in one of these ways: - removed the method, - renamed a parameter type, - changed a return type, - or moved the method to a supertype/subtype in a way that alters the descriptor, then at the moment the JVM tries to link that symbolic reference against the actual X 2.0 class on the runtime classpath, it cannot find a matching method and throws `NoSuchMethodError`. The equivalent failures for fields, abstract methods left unimplemented, and broader binary-layout changes are these: | What the newer version altered | The error you get | |---|---| | Fields | `NoSuchFieldError` | | Abstract methods left unimplemented | `AbstractMethodError` | | Broader binary-layout changes | the broader `IncompatibleClassChangeError` family | ## The trade-off underlying the design The trade-off underlying this whole design is the cost of separate compilation versus the cost of **deferred verification**. - Separate compilation is what lets a huge ecosystem of independently published libraries interoperate at all — nobody has to recompile the entire dependency graph from source every time one leaf library changes. - The price paid for that flexibility is that **binary compatibility** becomes an informal contract libraries must maintain themselves (by not removing or changing public method signatures across compatible versions) rather than something the compiler can verify end-to-end across the whole assembled application. - A library can be perfectly internally consistent and still break every downstream consumer that was compiled against an earlier version, purely by changing a signature the compiler considered a private implementation detail but that some consumer happened to call. ## The distinctive signature in production In production this failure mode has a distinctive signature: it is deterministic given a specific classpath and a specific code path, but it can appear to be **intermittent** from a user's point of view, because linking is **lazy** — the JVM only resolves a symbolic reference the first time that particular method call actually executes. A code path that's rarely exercised can carry a latent version mismatch through code review, CI, and weeks of production traffic before a user finally triggers it and gets a stack trace. Such a path might be: - an admin export feature, - an error-handling branch, - a feature flag most users don't hit. This is also why "the build passed" offers no real assurance here: each module's own compile step only validates against its own declared compile-time dependency, never against the final merged runtime classpath the application actually assembles. ## Two library families that show the pattern 1. **Google Guava.** A well-documented real-world instance of exactly this pattern involves the Google Guava library, which has repeatedly removed APIs marked `@Beta` or deprecated between major versions. Applications with two dependencies — one compiled against an older Guava, one pulling in and forcing a newer Guava transitively — have hit `NoSuchMethodError` in production once the dependency resolver collapsed the graph to a single Guava version that the older-compiled library was never built against. 2. **The Jackson JSON library family.** It addresses this proactively: `jackson-core`, `jackson-databind`, and `jackson-annotations` must all be the same minor version, and Jackson deliberately performs a runtime version check that throws an explicit `InvalidDefinitionException`/'Incompatible Jackson version' message rather than letting the mismatch surface as an opaque, hard-to-diagnose `NoSuchMethodError` deep in a stack trace — a pragmatic mitigation most libraries don't bother building because it requires extra runtime bookkeeping just to fail more legibly.