How to Fix java.lang.NoClassDefFoundError in Java

April 21st, 2021 • By Rollbar Editorial Team

Of all of the Java errors, the NoClassDefFoundError can be one of the trickiest to triage, identify, and fix.

Picture this: You are living your best life—solving business problems as a service developer on a feature team. You deliver value with every completed ticket using the Java programming language to accomplish your goals.

Life is great.

Then, things stop working. Something unexpected happened to your pristine service. You check the logs and see this error:

Exception in thread "main" java.lang.NoClassDefFoundError

Everything was working earlier, but now the service will not start.

Life is not-so-great.

Time to figure out what this error means, why it happened, and how to fix it.

What is the java.lang.NoClassDefFoundError?

The NoClassDefFoundError is an error that is thrown when the Java Runtime System tries to load the definition of a class that was available when the program was compiled but is no longer available at runtime.

To provide a simple example, consider the following Java code:

public class MyClass {
   // Your way-cool code goes here
}

public class MyApplication {
   public static void main(String[] args) {
       MyClass myclass = new MyClass();
       System.out.println(myclass.toString());
   }
}

When compiling classes, the compiler will validate the MyClass and MyApplicatio Java class files, then create corresponding MyClass.class and MyApplication.class files.

The java executable can be then used to run the MyApplication class, which will call the MyClass class as part of the main() method.

$ java MyApplication
MyClass@15db9742

However, if we were to manually delete the MyClass.class file from the file system and try to run the MyApplication class...

$ rm MyClass.class
$ java MyApplication

... the following error will appear:

Exception in thread "main" java.lang.NoClassDefFoundError: MyClass
at MyApplication.main(MyApplication.java:3)
Caused by: java.lang.ClassNotFoundException: MyClass
at java.net.URLClassLoader.findClass(URLClassLoader.java:382)
at java.lang.ClassLoader.loadClass(ClassLoader.java:418)
at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:355)
at java.lang.ClassLoader.loadClass(ClassLoader.java:351)
... 1 more

Now, as a feature developer, you're unlikely to navigate to the .class folders and manually delete files, then wonder why things stopped working. So, let's dive in to understand some real-world common scenarios when the NoClassDefFoundError occurs.

The How, When, and Why of the NoClassDefFoundError

While feature developers are unlikely to intentionally delete .class files created by the Java compiler, it is possible for an unrelated action to yield the same result.

Missing Class File

I recall working on a project that involved a collection of Java archive (.jar) files required by a database client and used by the application. Basically, the application configuration referenced a folder containing proprietary archives that were not meant to be distributed. Those files were read during the compilation and build process were also required during the run-time of the application.

The operations team performed an update to the client software for the database. What was not known at the time was that a depreciated class was removed within the collection .jar files. However, the application still had references to the once-deprecated, now-gone class. As a result, the NoClassDefFoundError and ClassNotFoundException began to occur in every instance where that software update was performed.

The same end result could also have occurred if the location of the Java archives was no longer on the class path. This could have happened if the client upgrade decided to start using a different location on the file system.

In short, a dependent class file which was available when the application was compiled and built is no longer available.

Static Variables and Static Initializer Blocks

Two other scenarios that are common sources for the NoClassDefFoundError error are related to logic issues within static variables and static initializer blocks.

Building upon the example above, consider the case where the MyClass class was configured as follows:

public class AnotherClass {
   static int divideByZero = 1 / 0;
}

Of course, the divideByZero computation will result in a divide-by-zero error which will surface as a java.lang.ExceptionInInitializerError. However, if we catch this error in one place, but fail to do so in another instance, the NoClassDefFoundError error will arise:

public class AnotherApplication {
   public static void main(String[] args) {
       try {
           AnotherClass anotherClass = new AnotherClass();
       } catch (Throwable t) {
           System.out.println(t);
       }

       AnotherClass anotherClassTwo = new AnotherClassg();
   }
}

The results of running the AnotherApplication class are displayed below:

$ java AnotherApplication
java.lang.ExceptionInInitializerError
Exception in thread "main" java.lang.NoClassDefFoundError: Could not initialize class AnotherClass
at AnotherApplication.main(AnotherApplication.java:9)

A similar situation will appear when the FinalClass class is modified to include a static initializer block as shown below:

public class FinalClass {
   static {
       int divideByZero = 1 / 0;
   }
}

Both scenarios demonstrate that it's possible to result in a NoClassDefFoundError when the program initially catches the java.lang.ExceptionInInitializerError but allows the program logic to continue. Once the same class is called again, the NoClassDefFoundError will surface, because the JVM knows that the class cannot be initialized. As a result, it treats the scenario as a class that cannot be found.

Fixing the NoClassDefFoundError

The biggest challenge with fixing the NoClassDefFoundError is to understand the source behind the error. While I can recall times when this error was a common issue during feature development, I can say that frameworks like Spring, dependency management (such as Maven and Gradle, and improved integration development environments (such as IntelliJ IDEA) have cut down on the amount of time I troubleshoot a NoClassDefFoundError.

Below is a checklist of items to follow when the cause of the NoClassDefFoundError is not immediately clear:

  1. Review log files for java.lang.ExceptionInInitializerError, which were an early indicator of the underlying source of the NoClassDefFoundError (as demonstrated above)
  2. If any external archives are referenced in your project, check for updates to those files (such as a database client software upgrade)
  3. Check the log files for a java.lang.LinkageError, which is also an indicator for the NoClassDefFoundError error
  4. Check for any customization or overrides to the Classpath via a script, manifest file or command line.

Rollbar and Error Handling

Understanding the NoClassDefFoundError provides developers with a knowledge base of how to triage, identify, and fix the unexpected issue.

Rollbar provides a different approach to application monitoring and troubleshooting. It's focused on not only agile development and continuous delivery, but on providing real-time visibility into your application without having to refresh cluttered log screens and mine mountains of data. In fact, using Rollbar allows support engineers to see how often the NoClassDefFoundError occurs at a macro level.

The data that arrives into the Rollbar dashboard not only delivers on the metrics expected by production support and DevOps teams, but also links to the underlying source code — even to the point where existing tickets can be linked to an unexpected event ... or a new ticket can be created directly from Rollbar itself.

Unlike traditional monitoring solutions, Rollbar focuses directly on the errors in the code, providing a continuous code improvement platform that helps developers proactively discover, predict, and remediate errors faster, before users report issues. For more information, please review the following URL:

Meet Continuous Code Improvement

Get the latest updates delivered to your inbox.