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.