java.lang.NoClassDefFoundError

NoClassDefFoundError occurs when a class present at compile time is missing at runtime. The JVM fails when loading it during execution, not during compilation.

What It Means

The compiler successfully resolved the class and generated bytecode referencing it. But when the JVM tries to load that class at runtime, it cannot find its definition. This usually indicates a classpath mismatch between build and execution environments.

Why It Happens

• A dependency JAR is present at compile time but absent at runtime.
• You built an executable JAR without including its dependencies (not a fat JAR).
• The class is in a different version of the library than expected.
• A static initializer failed, causing the classloader to mark the class as permanently broken.
• You’re using Maven/Gradle but running java -jar target/my-app.jar without dependencies.

How to Fix It

1. Build a fat JAR with all dependencies

With Maven Shade Plugin:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-shade-plugin</artifactId>
    <version>3.5.0</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals><goal>shade</goal></goals>
        </execution>
    </executions>
</plugin>

With Gradle:

jar {
    manifest { attributes 'Main-Class': 'com.example.Main' }
    from { configurations.runtimeClasspath.collect { it.isDirectory() ? it : zipTree(it) } }
}

2. Include the classpath when running

# Wrong — missing dependencies
java -jar my-app.jar

# Right — include all dependency JARs
java -cp "target/classes:lib/*" com.example.Main

3. Check for static initializer failures

A failed static block kills the class for the entire JVM session:

public class DatabaseConfig {
    static {
        // If this throws, the class is dead
        try {
            Connection conn = DriverManager.getConnection("bad:url");
        } catch (Exception e) {
            // Log and rethrow as ExceptionInInitializerError
            throw new RuntimeException("Failed to initialize DB", e);
        }
    }
}

4. Verify your build tool’s dependency tree

# Maven
mvn dependency:tree

# Gradle
gradle dependencies

Look for conflicts — a class that exists in multiple JARs may not be loaded from the one you expect.

5. Use the verbose classloader flag

java -verbose:class -jar my-app.jar

This prints every class as it loads. The last class before the error is the one that failed.