Parse Java ClassNotFoundException Stack Trace

Understanding Java ClassNotFoundException

ClassNotFoundException is thrown when the JVM cannot find a class at runtime through the class loader. Its cousin, NoClassDefFoundError, occurs when a class was available at compile time but missing at runtime. Both indicate classpath or dependency problems.

Stack Trace Example

java.lang.ClassNotFoundException: com.mysql.cj.jdbc.Driver
    at java.base/jdk.internal.loader.BuiltinClassLoader.loadClass(BuiltinClassLoader.java:641)
    at java.base/jdk.internal.loader.ClassLoaders$AppClassLoader.loadClass(ClassLoaders.java:188)
    at java.base/java.lang.ClassLoader.loadClass(ClassLoader.java:525)
    at java.base/java.lang.Class.forName0(Native Method)
    at java.base/java.lang.Class.forName(Class.java:375)
    at com.example.database.ConnectionFactory.createConnection(ConnectionFactory.java:34)

ClassNotFoundException vs NoClassDefFoundError

• ClassNotFoundException --- runtime class loading failure (e.g., Class.forName(), JDBC driver loading, reflection)
• NoClassDefFoundError --- class existed at compile time but is missing at runtime (usually a deployment/packaging issue)

Common Causes

• Missing JAR file in the classpath
• Incorrect Maven/Gradle dependency scope (compile vs runtime vs provided)
• Application server class loader isolation
• Fat JAR packaging that excludes transitive dependencies
• Version conflicts causing a class to be in a different package

Diagnosis Steps

1. Extract the fully qualified class name from the error message
2. Identify which library provides that class
3. Check your build tool (Maven pom.xml / Gradle build.gradle) for the dependency
4. Verify the dependency scope is correct for your deployment target
5. Check the actual classpath at runtime with -verbose:class JVM flag

Class Loader Hierarchy

Java uses a hierarchical class loader system: Bootstrap > Extension > Application > Custom. The stack trace shows the class loader chain, which helps identify whether the class is expected to be loaded by the application class loader or a container-specific one (e.g., Tomcat's WebappClassLoader).