NoSuchMethodError: Fix Java JAR Version Skew

It compiled cleanly. Tests passed. Then production threw NoSuchMethodError on a library call that's right there in the docs — com.example.Client.setTimeout(I)V or similar. The method exists in your IDE, in the Javadoc, in your build. It just doesn't exist in the JAR that actually loaded at runtime, because an older copy of the same library won the classpath race.

This is the signature injury of dependency skew: two versions of one library on the classpath, and the wrong one first. Transitive dependencies drag in old copies silently — your direct dependency wants v3, some other library drags v1, and Maven's nearest-wins rule picks v1. Everything compiles against v3's API and detonates against v1's reality.

This guide gives you the linkage playbook. You'll learn why it compiles yet fails, how mvn dependency:tree exposes the duplicate, how to read which JAR loaded with -verbose:class, how classpath order decides winners, and how BOMs and the enforcer plugin prevent recurrence. Plus the crisp split from NoSuchMethodException so you never chase the wrong one again.

Compiles Fine, Fails at Runtime: the Linkage Gap

Java splits method checking across two moments. At compile time, javac verifies the method exists in the compile classpath's library version — v3 with your new overload. At runtime, the JVM links each call against whatever class file it actually loads, with no recheck against v3. When an older duplicate wins, linking fails and the JVM throws NoSuchMethodError. The compile and the run disagreed about which library exists, and the run always has the last word.

The message is precise once you decode it: com.fasterxml.jackson.databind.ObjectMapper.writeValueAsBytes(Ljava/lang/Object;)[B names the class, method, parameter types in descriptors, and return type. Compare that descriptor against the loaded JAR's javap output — the overload will be absent there and present in the compile version. That comparison is the entire diagnosis; everything else is finding how the stale JAR got in.

The probe below prints where any class actually loaded from — the single most useful linkage diagnostic. Run it in production's JVM with the failing class name and it names the winning JAR outright. Teach every backend engineer this five-liner; it ends classpath arguments in seconds. Teach every backend engineer this five-liner; it ends classpath arguments in seconds instead of hours. Compare the descriptor against the loaded JAR's javap output and the gap stares back at you.

public final class ClassOrigin {
    public static void main(String[] args) throws Exception {
        String cls = args.length > 0 ? args[0]
                : "com.fasterxml.jackson.databind.ObjectMapper";
        Class<?> c = Class.forName(cls);
        System.out.println("loaded: " + c.getProtectionDomain().getCodeSource().getLocation());
        System.out.println("package: " + c.getPackage().getImplementationVersion());
    }
}
// Run: javac ClassOrigin.java && java -cp app.jar:. ClassOrigin
// Or trace everything: java -verbose:class -jar app.jar 2>&1 | grep ObjectMapper

dependency:tree: Exposing the Duplicate

Maven's dependency:tree prints every transitive path to each artifact, and duplicates show as multiple versions with different depths. Nearest-wins mediation picks the shallowest — so when your Jackson 2.17 sits at depth 3 and a metrics SDK's 2.9 sits at depth 2, the build silently runs 2.9. The tree makes this visible: look for the same artifactId with two versions, note the depths, and the winner is the nearer one. Gradle's dependencies task shows the equivalent with its own conflict notation.

Read the tree on every dependency change, not just during incidents. A one-line SDK bump can drag a dozen transitives; the tree diff against main shows exactly what moved. Pipe it to a file and diff: mvn dependency:tree > /tmp/after.txt, then diff /tmp/before.txt /tmp/after.txt. Version downgrades in that diff are rollback candidates before they ever package.

Exclusions and pins are the two repairs. An exclusion removes the stale transitive at its source; a dependencyManagement pin forces one version everywhere regardless of depth. Pins win for critical shared libraries like Jackson, logging, and HTTP clients — declare them once and let mediation argue with the pin instead of your runtime.

import java.util.ArrayList;
import java.util.List;

public final class DepVersions {
    public static List<String> jacksonVersions() {
        List<String> out = new ArrayList<>();
        for (Package p : Package.getPackages()) {
            if (p.getName().startsWith("com.fasterxml.jackson")) {
                out.add(p.getName() + " -> " + p.getImplementationVersion());
            }
        }
        out.sort(String::compareTo);
        return List.copyOf(out);
    }

    public static void main(String[] args) {
        jacksonVersions().forEach(System.out::println);
    }
}
// Two versions listed means skew: pin one in dependencyManagement

Classpath Order: Why Position Decides Truth

The JVM's search rule is brutally simple: first class file found for a name wins, later duplicates are invisible. On a flat classpath, order is truth — lib/a.jar before lib/b.jar means a.jar's classes shadow b.jar's same-named classes entirely. App servers add scoped layers (EAR, WAR, server lib) with parent-first or child-first delegation, each reordering which copy loads. Containers add one more shuffle when layer caching reorders COPY steps. Same code, different order, different winner.

Diagnose order with -verbose:class: it logs each class with its source JAR in load sequence, so the winner is the path printed beside the failing class. For layered servers, print the effective classpath per module and compare against the server's delegation docs. For fat JARs, order collapses into packaging — the shade plugin's include order and relocation rules decide, and only jar tf plus the plugin config reveal the outcome.

The durable fix reduces order's power: one version per library so order stops mattering. Dedupe first with pins and exclusions; manage layering second with server docs; debug order only for what's left. An explicit classpath you generate and log at startup beats a directory glob that reorders with every filesystem.

NoSuchMethodError vs NoSuchMethodException

The names differ by three letters and the universes differ completely. NoSuchMethodError (java.lang, unchecked Error) fires at runtime linkage when a compiled call can't resolve — your call is correct, the loaded library is stale. NoSuchMethodException (java.lang, checked Exception) fires from reflection — Class.getMethod or getDeclaredMethod found no match — meaning your lookup name or signature is wrong. One indicts JARs, the other indicts names.

The handling differs accordingly. The Error never gets caught for recovery — you fix the classpath, rebuild, and redeploy; catching it just postpones the same throw. The Exception is ordinary control flow in reflective code: catch it, fall back to another method, or report the bad name. Conflating them sends engineers editing method names for a JAR problem or rebuilding JARs for a typo.

The snippet shows the reflection side done right: lookup with explicit parameter types, catch the checked exception, fall back deliberately. When this catch fires, the diagnosis is the name or signature — print both, compare against javap of the target class, and fix the lookup. If instead the production trace shows the Error, close the reflection docs and open the dependency tree.

public final class ReflectLookup {
    public static String versionOf(Object mapper) {
        try {
            var m = mapper.getClass().getMethod("version"); // checked lookup
            Object v = m.invoke(mapper);
            return String.valueOf(v);
        } catch (NoSuchMethodException e) {
            return "unknown: no version() on " + mapper.getClass().getName();
        } catch (Exception e) {
            throw new IllegalStateException("version lookup failed", e);
        }
    }
}
// Error in prod trace -> fix JARs. Exception here -> fix names.

BOMs, Enforcer, and Locks: Prevention That Holds

Prevention means making version choice explicit and conflicts loud. A BOM (bill of materials) import pins a coherent set of library versions — Spring Boot's, Jackson's, AWS SDK's — so transitives align instead of fighting. dependencyManagement entries do the same per artifact for libraries outside any BOM. Together they convert mediation from positional accident to declared intent: the build resolves what you wrote, not what sits nearest.

The enforcer plugin's dependencyConvergence rule turns silent conflicts into build failures: any artifact arriving in two versions breaks the build until someone pins or excludes deliberately. Pair it with dependency:tree diffs in pull-request checks so version moves get human eyes. For Gradle, constraints and resolutionStrategy force rules plus dependency locking serve the same role — lockfiles committed to Git make every build resolve identically.

Add one runtime backstop: a smoke test that exercises serialization, HTTP, and reflection paths against the packaged artifact in CI. Linkage errors only exist in packaged form, so unit tests against compile classpaths can't catch them. The smoke test runs java -jar on the real artifact and fails the pipeline on any linkage Error — the incident in this article would have died there.

Reading the Descriptor and Locking the Fix

The Error's message is a precise fingerprint: com.example.Client.setTimeout(I)V breaks into class, method name, (I) int parameter, and V void return. Map each part: the class names the duplicated library, the method names what the stale copy lacks, the descriptor distinguishes overloads — setTimeout(I) missing while setTimeout(J) exists is still this Error. Compare with javap on both JARs and the gap stares back at you.

Lock the fix three ways. Pin the version in dependencyManagement so mediation can't drift it. Add the exclusion that removes the stale transitive at its source. Add the smoke test that calls the exact method against the packaged artifact — named for the incident, like serializesWebhookPayload, so history travels with the test. Any one lock can slip; three hold.

Record the conflict in the pull request: which library dragged the stale copy, what depth won, and what pin fixed it. The next engineer with a metrics-SDK bump reads that note and checks the tree before merging. Version-skew knowledge compounds across incidents until the build rules encode all of it. Version-skew knowledge compounds across incidents until the build rules encode all of it for future upgrades. Record the conflict source in the pull request so the next engineer checks the tree before merging.

public final class LinkageSmoke {
    public static void main(String[] args) throws Exception {
        // Exercises the exact linkage that failed: fails CI on skew.
        Class<?> c = Class.forName("com.fasterxml.jackson.databind.ObjectMapper");
        c.getMethod("writeValueAsBytes", Object.class); // throws if stale
        Object mapper = c.getDeclaredConstructor().newInstance();
        byte[] out = (byte[]) c.getMethod("writeValueAsBytes", Object.class)
                .invoke(mapper, java.util.Map.of("ok", true));
        System.out.println("linkage OK, bytes=" + out.length);
    }
}
// Run against the packaged artifact: java -cp app.jar:. LinkageSmoke