What's Actually Happening

Java cannot find a class at runtime. ClassNotFoundException or NoClassDefFoundError is thrown when the JVM cannot locate a required class.

The Error You'll See

java
java.lang.ClassNotFoundException: com.mysql.jdbc.Driver

Or:

java
java.lang.NoClassDefFoundError: org/apache/commons/lang3/StringUtils

Why This Happens

  1. 1.Missing JAR from classpath
  2. 2.Wrong classpath configuration
  3. 3.JAR not in WEB-INF/lib
  4. 4.Missing Maven/Gradle dependency
  5. 5.Wrong dependency scope
  6. 6.Class name typo

Step 1: Check Classpath

bash
echo $CLASSPATH
java -cp .:lib/* MyApp
java -classpath myapp.jar:lib/* com.example.Main

Step 2: Check JAR Files

bash
ls -la lib/
jar tf lib/mysql-connector.jar | grep Driver
unzip -l myapp.jar | grep MyClass

Step 3: Add Maven Dependency

xml
<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>8.0.33</version>
</dependency>

Step 4: Check Dependency Scope

xml
<dependency>
    <groupId>junit</groupId>
    <artifactId>junit</artifactId>
    <scope>test</scope>  <!-- Not available at runtime -->
</dependency>

Step 5: Build with Dependencies

bash
mvn clean package
mvn dependency:copy-dependencies -DoutputDirectory=target/lib
java -cp target/myapp.jar:target/lib/* com.example.Main

Step 6: Use Fat JAR

xml
<plugin>
    <artifactId>maven-assembly-plugin</artifactId>
    <configuration>
        <archive><manifest><mainClass>com.example.Main</mainClass></manifest></archive>
        <descriptorRefs><descriptorRef>jar-with-dependencies</descriptorRef></descriptorRefs>
    </configuration>
</plugin>

Step 7: Check WEB-INF/lib

bash
ls -la src/main/webapp/WEB-INF/lib/
jar tf myapp.war | grep WEB-INF/lib

Step 8: Verify Class Exists

bash
javap -cp lib/myjar.jar com.example.MyClass
jar tf lib/myjar.jar | grep MyClass

Step 9: Debug Classpath

java
System.out.println(System.getProperty("java.class.path"));
System.out.println(ClassLoader.getSystemClassLoader().getResource("com/example/MyClass.class"));

Step 10: Verify Runtime

bash
java -verbose:class -cp myapp.jar com.example.Main 2>&1 | grep MyClass
mvn dependency:tree
  • [Fix Java NoSuchMethodError](/articles/fix-java-no-such-method-error)
  • [Fix Java OutOfMemoryError](/articles/fix-java-out-of-memory-error)