Monday, June 30, 2008

Tip: Causes of java.lang.ClassNotFoundException

Class loading issues are a common frustration for many Java developers. The dreaded java.langClassNotFoundException means they can forget about going home at a reasonable hour. While Java class loading is very powerful feature, it is also a very flexible and confusing feature. But don’t let this exception scare you. The majority of the time, there are three very practical things to look at in order to resolve the issue.
  1. If you are loading a class by name either using Class.forName() or an Inversion of Control container like Spring it may be as simple as the class name was spelled incorrectly. Validate the fully qualified class name is spelled correctly. The best way is to use the Eclipse “Copy Qualified Name” feature or copying and pasting the package name and class name directly from the source file.
  2. The mostly likely culprit is the class can not really be found. This can be caused by the directory or jar file containing class not being included in the JVM classpath. The other common cause when multiple class loaders are involved such as in a web container or application server is a visibility problem. For example classes in an ejb-jar do not have access to classes in the war file for the majority of application servers. But classes in the war file have access to classes in the ejb-jar. The reason is the war file typically has its own class loader which is a child class loader of the ear class loader. The basic rule is children class loaders have access to their parents but not visa versa. For this error, check your application server’s class loading documentation and make sure the class that is trying to access the not found class has the acceptable access.
  3. The most challenging cause to debug is a dependency issue during initialization of a class. During initialization if a class can’t find certain resources it depends on such as other classes or files, this may result in a ClassNotFoundException. To resolve this, you may need to validate all dependencies are available. If you have the code, you can look at the class imports and any static initilization. If you don’t, you might need to reverse engineer the class to determine the dependencies.
I hope this helps. Just remember the cause of ClassNotFoundExceptions can be difficult to resolve but they are always deterministic so stick with it.


men2day said...
This comment has been removed by the author.
Javin Paul said...

As per java doc java.lang.classNotFoundException comes in following cases:
1) When we try to load a class by using Class.forName () method and Class is not available in classpath.
2) When Classloader try to load a class by using findSystemClass () method.
3) While using loadClass() method of class ClassLoader in Java.

and it could be even more difficult to find out the real cause in integrated environment like J2EE where different web server use different classloaders and it can come if class is not visible to classloader.

NoClassDefFoundError vs ClassNotFoundException

P-H said...

Hi Chris and nice tips on how to resolve java.lang.ClassNotFoundException problems.

Sometimes the root cause can be simple or very hard such as complex classloader problems. As per Javin, it can be particularely challenging when debugging such problem within a big Java EE system with dozens of applications deployed.

Java EE Support Patterns

john wright said...

Thanks for the post, I am techno savvy. I believe you hit the nail right on the head. I am highly impressed with your blog.
It is very nicely explained. Your article adds best knowledge to our Java Online Training from India.
or learn thru Java Online Training from India Students.

The Ultimate Enterprise Java Build Solution Revisited

In May of 2009, I wrote the blog post The Ultimate Enterprise Java Build Solution . Over the past 7 years since I wrote the post I have help...