Fix ClassNotFoundException and NoClassDefFoundError in Java

Introduction

Java developers often face two common errors: ClassNotFoundException and NoClassDefFoundError. These errors occur when Java cannot locate a class during execution or compiling. Although they may look similar, their causes are different. Understanding these errors is important for debugging applications, especially when working with large projects, external libraries, or frameworks. In this article, we will explain both errors in simple language and provide detailed solutions for each scenario.

What is ClassNotFoundException?

ClassNotFoundException occurs when Java cannot find a class at runtime.

This usually happens when:

A required library is missing from the classpath
You are using reflection (Class.forName())
A dependency is not packaged properly in a JAR
A wrong path is used while loading classes dynamically

Example

Class.forName("com.example.MyService");

If MyService is not in the classpath, this will throw:

java.lang.ClassNotFoundException: com.example.MyService

What is NoClassDefFoundError?

NoClassDefFoundError occurs when Java found the class during compile time but cannot find it during runtime.

This usually happens when:

The class was deleted or moved after compilation
The compiled JAR is missing required classes
A dependency failed to load
File permissions prevent Java from reading the class

Example

You compile successfully, but when running:

Error: java.lang.NoClassDefFoundError: com/example/MyService

This means Java knew about the class earlier but cannot load it now.

Key Difference Between the Two

Feature	ClassNotFoundException	NoClassDefFoundError
Type	Checked exception	Error (unchecked)
When it occurs	During runtime	During runtime after successful compile
Reason	Java cannot locate class in classpath	Java located class earlier but cannot load it now
Common cause	Missing dependencies	Missing or corrupted compiled class

Common Causes and Fixes

Let's explore detailed solutions for both errors.

Solution 1: Fix Classpath Issues

Most problems occur because Java cannot find the required class.

How to Fix

Add missing JAR files to classpath
Ensure correct folder structure
Use absolute paths in scripts

Example (Fix classpath in command-line)

java -cp .:lib/* com.example.MainApp

(Use ; instead of : on Windows)

Maven Fix

Ensure dependency exists in pom.xml:

<dependency>
  <groupId>org.example</groupId>
  <artifactId>my-library</artifactId>
  <version>1.0</version>
</dependency>

Run:

mvn clean install

Solution 2: Fix Missing Dependencies in IDE (Eclipse/IntelliJ)

Sometimes the project compiles but fails at runtime.

IntelliJ Fix

Go to File → Project Structure → Modules
Ensure all required libraries are added
Rebuild project

Eclipse Fix

Right-click project → Build Path → Configure Build Path
Add missing JARs
Clean project: Project → Clean

Solution 3: Fix Errors Caused by Reflection

Reflection loads classes dynamically. If the class name is wrong or missing, it causes ClassNotFoundException.

Example Fix

try {
    Class<?> clazz = Class.forName("com.example.service.UserService");
} catch (ClassNotFoundException e) {
    e.printStackTrace();
}

Check

Spelling
Package name
Availability in classpath

Solution 4: Fix NoClassDefFoundError Due to Deleted or Moved Class

If a class was available during compile time but removed later, Java throws NoClassDefFoundError.

Fix

Rebuild entire project to regenerate all .class files
Ensure correct build output folder
Do not manually delete class files

Example

If your build folder structure changed:

target/classes/com/example

Make sure your IDE is pointing to the right location.

Solution 5: Fix Packaging Issues (JAR Files)

When using a JAR file, missing classes inside the JAR cause these errors.

How to check

jar tf myapp.jar

If class is missing → packaging problem.

Fix

Update build plugins (Maven Shade Plugin or Spring Boot Plugin)
Rebuild JAR

Example Maven Shade Plugin

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

Solution 6: Fix Version Conflicts

Sometimes two libraries depend on different versions of the same class.

Fix

Check dependency tree

mvn dependency:tree

Remove conflicting JARs
Use dependency exclusions:

<dependency>
  <groupId>group</groupId>
  <artifactId>artifact</artifactId>
  <exclusions>
    <exclusion>
      <groupId>x.y.z</groupId>
      <artifactId>conflict-lib</artifactId>
    </exclusion>
  </exclusions>
</dependency>

Solution 7: File Permission or OS Path Issues

On Linux systems, missing permissions for .class files can cause errors.

Fix

chmod -R 755 target/classes

Ensure no restricted directories.

Real-Life Example

A Java developer in Bengaluru deploys a Spring Boot application to a Linux server. Locally, everything works fine. But on the server, the app throws:

java.lang.NoClassDefFoundError: org/apache/logging/log4j/Logger

The reason: The Log4j dependency was marked as provided in Maven, so it was not included in the final JAR. Adding the full dependency resolved the problem.

Best Practices to Avoid These Errors

Always clean and rebuild your project
Use Maven/Gradle instead of manual JAR management
Avoid duplicate or conflicting libraries
Keep consistent IDE settings across team members
Check spelling and package structures carefully
Use dependency management tools (Maven, Gradle)

Summary

ClassNotFoundException and NoClassDefFoundError are common Java runtime errors caused by missing, moved, or incorrectly packaged classes. By fixing classpath issues, verifying dependencies, rebuilding projects, checking packaging, and avoiding version conflicts, you can quickly resolve these errors and ensure a smooth Java development experience.