How to Fix java.lang.NoClassDefFoundError: org/dom4j/DocumentException [Solution]

Exception in thread "main" java.lang.NoClassDefFoundError: org/dom4j/DocumentException comes when your program is using the DOM4j library but necessary JAR is not present. This error can also come when you are indirectly using the DOM4j library like  when you use the Apache POI library to read the XLSX file in Java,  this library needs dom4j.jar in your classpath. Not just this one but there are several other libraries that use this JAR internally, if you are using any of them but don't have this JAR then your program will compile fine but fail at runtime because JVM will try to load this class but will not be able to find it on the classpath. 

Alert and curious developers might ask, why it didn't fail during compile time if JAR was not present there? Well, the reason for that is that your code might not be using any class file directly from the dom4j.jar file.

When you compile your program like ExcelReader.java, then the compiler will only look for a class file that is directly referenced or required to generate the class file, it will not look for transitive dependencies.

For example, suppose you need WorkBook class from Apache  POI, which internally uses dom4j library, the compiler will complain if poi.jar is not there, but will not complain even if dom4j.jar is not present because it's compiling your code, it's not compiling WorkBook class, it's already compiled because the class file of this code is already present in poi.jar. But things work differently when your run the program, at that time JVM will look for all the binary code.

When it will load WorkBook class it will try to load the referenced class from the DOM4j library and at that time if JVM didn't find those classes in CLASSPATH, it will throw java.lang.NoClassDefFoundError: org/dom4j/DocumentException.

It can also come as java.lang.ClassNotFoundException: org.dom4j.DocumentException but only if your code tries to load this class explicitly instead of JVM. That's actually the difference between ClassNotFoundException and NoClassDefFoundError in Java. Now million dollar question? How do you solve this error? Just add a dom4j-1.6.1.jar file into the classpath.

Cause of java.lang.NoClassDefFoundError: org/dom4j/DocumentException in Java

As I said the root cause of this error is the missing dom4j JAR file. It could be due to direct dependency or third-party dependency e.g. you are using Apache POI library to read and write Excel file in Java and that library needs dom4j JAR file but you have only include poi.jar into your classpath.  Here is how the stack trace of this error will look like :

Exception in thread "main" java.lang.NoClassDefFoundError: org/dom4j/DocumentException
        at org.apache.poi.openxml4j.opc.OPCPackage.init(OPCPackage.java:154)
        at org.apache.poi.openxml4j.opc.OPCPackage.<init>(OPCPackage.java:141)
        at org.apache.poi.openxml4j.opc.Package.<init>(Package.java:54)
        at org.apache.poi.openxml4j.opc.ZipPackage.<init>(ZipPackage.java:82)
        at org.apache.poi.openxml4j.opc.OPCPackage.open(OPCPackage.java:228)
        at org.apache.poi.util.PackageHelper.open(PackageHelper.java:39)
        at org.apache.poi.xssf.usermodel.XSSFWorkbook.<init>(XSSFWorkbook.java:1
87)
        at ExcelReader.main(ExcelReader.java:12)
Caused by: java.lang.ClassNotFoundException: org.dom4j.DocumentException
        at java.net.URLClassLoader$1.run(Unknown Source)
        at java.net.URLClassLoader$1.run(Unknown Source)
        at java.security.AccessController.doPrivileged(Native Method)
        at java.net.URLClassLoader.findClass(Unknown Source)
        at java.lang.ClassLoader.loadClass(Unknown Source)
        at sun.misc.Launcher$AppClassLoader.loadClass(Unknown Source)
        at java.lang.ClassLoader.loadClass(Unknown Source)
        ... 8 more

Let's try to understand this error stack-trace in detail. You can see that root cause of this error is  "java.lang.ClassNotFoundException: org.dom4j.DocumentException", which suggests bye "Caused by :" line. You can see that JVM was trying to load that class from the reference of "java.net.URLClassLoader". 

If you move up you can also see that this error was initiated from your code at ExcelReader.main(ExcelReader.java:12), which is the 12th line of your ExcelReader.java source file, which is nothing but a simple program that read data from XLSX file in Java. 

If you remember correctly, XLSX  is an Open XML format file and you need the poi-ooxml-XX.jar file to read that file.  A class called org.apache.poi.openxml4j.opc.OPCPackage needs org.dom4j.DocumentException and their JVM failed because it didn't found org.dom4j.DocumentException class because the JAR file which contains this class file is not present in CLASSPATH. 

How to solve java.lang.NoClassDefFoundError: org/dom4j/DocumentException

If you understand the cause of this problem and solution is easy.  This exception can be solved by adding dom4j-1.6.1.jar to the classpath. The exact version of the JAR file depends on your code or third-party library which is using this JAR file. 

It may possible that adding arbitrary JAR may result in some other error or exception. Usually, this type of error comes when you manually manage your project dependencies by downloading JAR files from the internet. 

I suggest using Apache Maven to manage project dependencies because it also downloads transitive dependencies e.g. if you had used Maven to download poi-ooxml-XX.jar then it would have automatically downloaded the dom4j-XX.jar file. 

If there is no choice and you have to add JAR files manually then make sure you read about third-party dependencies of your library and download the correct version of JAR files. 

That's all about how to solve java.lang.NoClassDefFoundError: org/dom4j/DocumentException error in Java. As you have seen this error comes when your project is using org.dom4j.DocumentException class either directly or indirectly but the dom4j-1.6.1.jar file is not present in CLASSPATH. In order to solve java.lang.NoClassDefFoundError: org/dom4j/DocumentException just add dom4j-1.6.1.jar file into your program's classpath. 

Java Troubleshooting Tutorials

• What is difference between Error and Exception in Java? (answer)
• Difference between RuntimeException and checked exception in Java? (answer)
• Difference between throw and throws in Java? (answer)
• How to create user defined exception in Java? (answer)
• How to fix java.lang.OutOfMemoryError: Direct buffer memory in Java (solution)
• How to solve java.lang.ClassNotFoundException: org.apache.xmlbeans.XmlObject? (solution)
• Could not create the Java virtual machine Invalid maximum heap size: -Xmx (solution)
• java.lang.unsupportedclassversionerror unsupported major.minor version 50.0? (solution)
• How to deal with org.springframework.web.context.ContextLoaderListener ? (solution)
• How to solve java.lang.OutOfMemoryError: Java heap space in Tomcat and Eclipse? (solution)
• How to fix  java.lang.classnotfoundexception oracle.jdbc.driver.oracledriver in Java? (solution)

You can also use the same solution to solve java.lang.ClassNotFoundException: org.dom4j.DocumentException error as well, because both are the exact same only difference is that in the case of former JVM initiated the process of loading a class and in the case of later your code explicitly tried to load the class file.