java.lang.ClassNotFoundException / java.lang.NoClassDefFoundError

The exact error strings

// explicit, by-name load — the class genuinely isn't on the classpath:
java.lang.ClassNotFoundException: com.mysql.cj.jdbc.Driver
	at java.base/java.net.URLClassLoader.findClass(URLClassLoader.java:445)
	at com.example.App.main(App.java:9)

// implicit load — bytecode already references this class:
Exception in thread "main" java.lang.NoClassDefFoundError: com/example/PaymentProcessor
	at com.example.App.main(App.java:14)
Caused by: java.lang.ClassNotFoundException: com.example.PaymentProcessor
	at java.base/java.net.URLClassLoader.findClass(URLClassLoader.java:445)
	... 1 more

Note the second example: a NoClassDefFoundError can itself be caused by a ClassNotFoundException underneath — the JVM's implicit resolution mechanism internally uses the same by-name classloading lookup, and when that lookup fails, the outer implicit-load failure surfaces as the Error, with the inner ClassNotFoundException chained as its cause. Seeing both in one trace does not mean two separate bugs; it means one missing-classpath-entry problem, surfaced through the implicit-load path.

The two-phase classloading model, visually

Cause 1 (NoClassDefFoundError): a jar present at compile time, missing at runtime

# build succeeds — the dependency jar is on the build tool's classpath:
mvn package
# BUILD SUCCESS

# but the deployed/runtime environment (a Docker image, a manually
# assembled classpath) never copied that jar into it:
java -cp app.jar com.example.App
# Exception in thread "main" java.lang.NoClassDefFoundError: ...

# ✅ ensure every compile-time dependency is also included in the
#    runtime artifact — e.g. a "fat jar" / shaded jar bundling all
#    dependencies, or an explicit COPY step in a Dockerfile

Compilation and execution consult two logically separate classpaths, and build tools like Maven and Gradle can make this distinction invisible during local development (where both classpaths happen to line up) while a deployment pipeline silently diverges them — a common cause is a multi-stage Docker build where the compile stage has full access to a dependency cache, but the final runtime image only copies the application's own class files and forgets to also copy the third-party jars it depends on. The class was never missing from the code; it's missing from the specific artifact that actually gets run.

Cause 2 (NoClassDefFoundError): a static initializer that already failed once

public class Config {
    static final int MAX = 100 / Integer.parseInt(System.getenv("LIMIT"));
    // ❌ throws NumberFormatException the FIRST time Config is loaded,
    //    if LIMIT isn't set or isn't a valid number
}

// first call anywhere in the program:
Config.MAX;   // throws ExceptionInInitializerError (the real root cause)

// every LATER attempt to use Config in the same JVM run:
Config.MAX;   // throws NoClassDefFoundError — Java won't retry a class
              // whose static init already failed once

The JVM guarantees a class's static initializer runs at most once per classloader per run — if that one attempt throws, the class is permanently marked as failed-to-initialize for the remainder of that JVM instance, and Java refuses to retry it, throwing NoClassDefFoundError on every subsequent reference instead. This produces a genuinely confusing trace: the exception you're staring at (NoClassDefFoundError) is not the actual bug — the real cause is an ExceptionInInitializerError from the first failed attempt, which may be much earlier in the log, or even in a different thread that happened to touch the class first.

Cause 3 (ClassNotFoundException): an explicit reflective/driver load with no matching jar

// older-style JDBC code explicitly force-loads the driver class by name:
Class.forName("com.mysql.cj.jdbc.Driver");
// ❌ java.lang.ClassNotFoundException: com.mysql.cj.jdbc.Driver
//    (the mysql-connector-j jar isn't on the classpath at all)

// ✅ add the driver dependency (Maven example):
// 
//   com.mysql
//   mysql-connector-j
//   8.x
// 

This is the textbook case of the "explicit, by-name" trigger: the code itself decided, at runtime, to ask the classloader for a specific fully-qualified class name — most classically to register a JDBC driver, but the same pattern appears in plugin systems, dependency-injection frameworks scanning for implementations, and any reflection-based "load a class by string" mechanism. Because the request names the class as a plain string rather than referencing it through compiled bytecode, the compiler never gets a chance to verify the class exists at all; the failure is discovered purely at runtime, the first time that string is actually resolved.

Common variants at a glance

Why this happens: Java resolves classes at two distinct times, for two distinct reasons

The compiler's job is narrower than it looks: it only verifies that every class your code references is resolvable on the compile-time classpath, and emits bytecode with symbolic references to those classes — it does not, and cannot, guarantee anything about what classpath the program will actually run against later. The JVM performs its own, separate resolution at runtime, and it does so in exactly two ways: implicitly, the moment compiled bytecode's reference to a class is first actually needed (triggering NoClassDefFoundError on failure), or explicitly, when application code deliberately asks for a class by name via reflection (triggering ClassNotFoundException on failure). Understanding which of these two paths produced your error immediately tells you where to look: an implicit failure means something about your deployment's classpath diverged from what you built against, while an explicit failure means a reflectively-requested dependency was never added to the classpath in the first place.

Debugging checklist

• ✓ Identify which error you actually have — ClassNotFoundException (explicit) or NoClassDefFoundError (implicit)
• ✓ For NoClassDefFoundError, scroll up in the log for an earlier ExceptionInInitializerError from the same class
• ✓ Confirm the dependency jar is actually bundled in the runtime artifact, not just the build classpath
• ✓ Run a dependency-tree command (mvn dependency:tree / gradle dependencies) to spot a version conflict
• ✓ For a reflective/driver load, confirm the exact fully-qualified class name matches the dependency's actual package