Load-Time Failures & LinkageError

## Two doors into the loader Every class in a running JVM is produced by some class loader, but requests reach the loader through one of two doors, and each door has its own failure signal. The **explicit door** is the reflective API: `Class.forName(String)`, `Class.forName(String, boolean, ClassLoader)`, `ClassLoader.loadClass(String)`, and everything built on them (object deserialization, service lookup, `Class.forName` inside a framework that instantiates a handler named in a config file). Here the class name is a *string* supplied at runtime. If no loader in the delegation chain can find a definition for that name, `loadClass` throws **`ClassNotFoundException`**, a checked `Exception`. Because it is checked, the calling code was written knowing this could happen; frameworks usually wrap it ("driver class not found", "cannot instantiate listener"). The **implicit door** is symbolic resolution from bytecode. When javac compiles `new Foo()` or a call `bar.baz()`, it does not embed Foo's definition. It writes a *symbolic reference* into the constant pool: the class name, and for members, the name plus descriptor. When the JVM first executes an instruction that needs that reference to be concrete, it resolves it, which means loading the referenced class. If loading fails there, you do not get a checked exception, because no source-level code declared it. You get **`NoClassDefFoundError`**, a subclass of `LinkageError`, which is an `Error`. ## Why the distinction is meaningful The distinction is not cosmetic; it tells you *who* expected the class to exist. `ClassNotFoundException` means some component chose to look up a name dynamically and came up empty. Typical causes: a typo in a fully qualified name in configuration, a plugin JAR that was never added to the runtime classpath, or a lookup performed with the *wrong* loader (a library asks its own defining loader for a class that only the application loader can see, which is the classic container/SPI problem). `NoClassDefFoundError` means compiled code already assumed the class exists. Something removed it between compile time and run time: a `provided`-scope dependency that never shipped, a fat-JAR build that pruned a transitively-needed artifact, a shaded/relocated package, or a runtime image built by `jlink`/a minimal container missing a module. The compile step passed precisely because the class was there *then*. ## The second cause of NoClassDefFoundError: an already-failed class The JVM initializes each class at most once per defining loader, and it records the outcome. If the static initializer throws, the class enters the *erroneous* state permanently. The very first thread to trigger initialization sees `ExceptionInInitializerError`; **every subsequent use of that class throws `NoClassDefFoundError` with the message `Could not initialize class x.Y`**. The bytes were found; the type simply cannot be used. This is why the message text matters: `NoClassDefFoundError: x/Y` is a missing-class problem, while `NoClassDefFoundError: Could not initialize class x.Y` is a downstream symptom whose root cause is an earlier stack trace, often on a different thread and often swallowed by a logging framework. ## Chaining, and how one becomes the other A loader that fails to find bytes throws `ClassNotFoundException`. When that failure happens under *resolution* rather than a direct API call, the JVM converts it: it throws `NoClassDefFoundError` with the `ClassNotFoundException` as its cause. That is why you often see a `NoClassDefFoundError` whose `Caused by:` is a `ClassNotFoundException` for the same name. Reading it top-down: the outer error says "compiled code needed this type"; the inner exception says "and the loader could not find it". ## Type hierarchy and handling `ClassNotFoundException` sits under `ReflectiveOperationException` under `Exception`. `NoClassDefFoundError` sits under `LinkageError` under `Error`. Catching the exception is normal and often correct (optional integration absent: fall back). Catching the error is defensible only in narrow places, for example probing whether an optional library is present, and even then only around the specific probing call; the class stays broken afterwards, and an erroneous class never recovers within that loader. ## Diagnosing Both are classpath archaeology. Print the effective classpath at startup; run with `-Xlog:class+load=info` (Java 9+) or `-verbose:class` to see which loader defined what and from which file; use `jar tf` or `jdeps` to confirm the artifact actually contains the package. For `Could not initialize class`, stop hunting the classpath and go find the first failure instead.