How to Fix Java Classpath Errors

In this tutorial, you'll learn about How to Fix Java Classpath Errors. We cover key concepts, practical examples, and best practices.

The Problem

Your Java application throws java.lang.ClassNotFoundException, java.lang.NoClassDefFoundError, or Exception in thread "main" java.lang.NoClassDefFoundError. The code compiles but fails at runtime because the JVM cannot find required classes.

Quick Fix

Fix 1: ClassNotFoundException at Runtime

WRONG — running with an incomplete classpath:

java Main
# Exception in thread "main" java.lang.NoClassDefFoundError: com/google/gson/Gson

RIGHT — include the JARs in the classpath:

java -cp .:lib/gson-2.10.1.jar Main
# (runs successfully)

For multiple JARs:

java -cp ".:lib/*" Main
# (wildcard includes all JARs in lib/)

Fix 2: NoClassDefFoundError vs ClassNotFoundException

# NoClassDefFoundError: A class was available at compile time but missing at runtime
# ClassNotFoundException: Class.forName() or ClassLoader.loadClass() failed

RIGHT — identify which class is missing:

java -verbose:class Main 2>&1 | grep "ClassNotFoundException\|NoClassDefFoundError"
# [class, load] com.example.MyClass source: file:/app/lib/missing.jar

Fix 3: Maven/Gradle Dependency Not Included in JAR

WRONG — building an uber-JAR without the maven-shade-plugin:

java -jar myapp.jar
# Exception in thread "main" java.lang.NoClassDefFoundError: org/slf4j/LoggerFactory

RIGHT — create a fat JAR with all dependencies:

<!-- pom.xml -->
<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>

mvn package
java -jar target/myapp-shaded.jar
# (runs with all dependencies included)

Fix 4: Duplicate Classes in Classpath

# Class path contains multiple SLF4J bindings:
# Warning: Multiple SLF4J bindings found on class path

RIGHT — exclude the duplicate:

<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-simple</artifactId>
    <version>2.0.9</version>
    <exclusions>
        <exclusion>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-api</artifactId>
        </exclusion>
    </exclusions>
</dependency>

Fix 5: Java 9+ Module Path Issues

# Error: java.lang.module.FindException: Module com.google.gson not found

RIGHT — add the module to the module path:

java --module-path lib/gson-2.10.1.jar --module my.module/com.example.Main

Or use the classpath with --add-modules:

java --add-modules java.xml.bind -cp ".:lib/*" Main

Fix 6: Boot Classpath vs Classpath

# For JAXB/Java EE APIs removed in Java 11:
# javax.xml.bind.JAXBContext not found

RIGHT — add the missing API as a dependency:

<dependency>
    <groupId>javax.xml.bind</groupId>
    <artifactId>jaxb-api</artifactId>
    <version>2.3.1</version>
</dependency>

Or add via --add-modules for older Java versions (8-10).

Use DodaTech's Classpath Inspector to visualize JAR dependencies, detect duplicate classes, and identify class loading conflicts in your application.

Prevention

• Use build tools (Maven/Gradle) to manage the classpath automatically.
• Build fat JARs with maven-shade-plugin or spring-boot-maven-plugin.
• Check for duplicate classes with mvn dependency:tree.
• Use -verbose:class to debug class loading issues.
• Test the executable JAR before deployment.

Common Mistakes with classpath error

1. Misunderstanding that String is [Char] with poor performance for large text operations
2. Using foldl instead of foldl' causing stack overflow on large lists
3. Forgetting deriving (Show, Eq) on custom data types needed for debugging

These mistakes appear frequently in real-world JAVA code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ