Java NoClassDefFoundError — What It Means & How to Fix It

What Does This Error Mean?

A NoClassDefFoundError means a class was present when your code was compiled, but cannot be found when the program actually runs. This is different from ClassNotFoundException — you never explicitly asked Java to load this class by name. Java needed it automatically (because your code uses it), but it was missing from the runtime environment. The most common cause is a missing JAR file that was not included in the deployment.

Affected Models

Java 8
Java 11
Java 17
Java 21
All Java versions

Common Causes

A required JAR file is missing from the runtime classpath — it was available during compilation but not included in deployment
The class is in a module that is not accessible in Java 9+ module system (JPMS) due to missing 'requires' declarations
An earlier class loading failure left the class in a 'failed to load' state — subsequent attempts get NoClassDefFoundError
The class was excluded by packaging tools, shading plugins, or ProGuard during the build process
A dependency scope issue in Maven or Gradle — a dependency marked as 'provided' or 'test' is not available at runtime

How to Fix It

Read the error message to get the exact class name. For example: 'NoClassDefFoundError: org/apache/commons/lang3/StringUtils' tells you the Apache Commons Lang library is missing at runtime.

The class name uses forward slashes (org/apache/...) instead of dots in error messages — convert to dots to find the library: org.apache.commons.lang3.StringUtils.
Find which library contains that class. Search the class name in Maven Central (search.maven.org) or check your project dependencies. That library needs to be on the runtime classpath.

In Maven, run mvn dependency:tree to see all dependencies. Find the one containing the missing class and make sure it is not scoped as 'provided' or 'test' unless that is intentional.
If you are packaging your application as a JAR, make sure all dependencies are included. Build a fat JAR (uber JAR) using the Maven Shade Plugin or the Maven Assembly Plugin.

A regular JAR contains only your compiled code. A fat JAR also includes all dependency JARs bundled inside it. Running a regular JAR without the dependencies on the classpath causes this error.
Check if an earlier exception caused the class to fail to load. NoClassDefFoundError sometimes appears after another error during class initialization. Look for earlier exceptions in the log above this error.

If a static initializer (static { ... } block) throws an exception, the class is marked as failed. Every subsequent attempt to use it throws NoClassDefFoundError, not the original error.
For Java 9+ module system errors, check your module-info.java. If the missing class is in another module, add a 'requires' directive for that module.

Example: requires org.apache.commons.lang3; — this tells the module system your code depends on that module.

When to Call a Professional

NoClassDefFoundError is an Error, not a recoverable Exception — it represents a serious environment configuration problem. It almost always means the deployed application is missing a required library. Compare the compile-time classpath to the runtime classpath to find what is missing.

Frequently Asked Questions

What is the difference between NoClassDefFoundError and ClassNotFoundException?

ClassNotFoundException is thrown when you explicitly try to load a class by name (using Class.forName() or a classloader) and it is not found. NoClassDefFoundError is thrown by the JVM automatically when it tries to load a class referenced in your bytecode and cannot find it. ClassNotFoundException is more about dynamic loading. NoClassDefFoundError is about missing compile-time dependencies at runtime.

Why is this an Error and not an Exception?

In Java, Errors represent conditions so serious that the application probably cannot recover from them. A missing class makes it impossible for affected code to run at all. Errors are not meant to be caught and handled — they signal environment problems that need to be fixed before the application can work.

What does it mean when the error says 'Could not initialize class'?

This means the class was found, but it failed during its static initialization phase (its static { } block or static field initializations threw an exception). The class is then permanently marked as failed. Any subsequent attempt to use it throws NoClassDefFoundError with 'Could not initialize class'. Check earlier in the logs for the original exception that caused the initialization failure.