How to Fix java.lang.NoClassDefFoundError: org/w3c/dom/ls/DocumentLS During JDK 11 to JDK 17 Migration

Migrating a Spring Boot application from JDK 11 to JDK 17 can sometimes lead to unexpected runtime errors, especially when dealing with XML parsing and dependencies. One such common error is the java.lang.NoClassDefFoundError: org/w3c/dom/ls/DocumentLS. This error typically occurs when the required DocumentLS class from the org.w3c.dom.ls package is missing at runtime. In this post, we’ll explore the root cause of this issue and provide step-by-step solutions to resolve it.

Understanding the Error

The error message:

Caused by: java.lang.NoClassDefFoundError: org/w3c/dom/ls/DocumentLS

indicates that the DocumentLS class, which is part of the DOM Level 3 Load and Save (LS) module, is not found in the classpath. This class is often required for XML parsing and manipulation in Java applications.

Why Does This Happen During JDK 11 to JDK 17 Migration?

• JDK Modularization: Starting from JDK 9, Java introduced the Java Platform Module System (JPMS), which modularized the JDK. Some classes that were previously part of the JDK were moved to separate modules or removed.
• Missing Dependencies: The DocumentLS class is part of the org.w3c.dom.ls package, which is not included by default in JDK 17. If your application relies on this class, you need to explicitly add the required dependency.

Root Cause Analysis

In your case, the error occurs because:

1. The DocumentLS class is not available in the classpath at runtime.
2. The xercesImpl dependency (which provides the DocumentLS implementation) is either missing or not properly configured.
3. The Spring Boot application is trying to parse an XML file (SpringConfiguration.xml), and the required DOM Level 3 classes are not found.

Solution: Fixing the NoClassDefFoundError

Step 1: Add the Required Dependency

The DocumentLS class is provided by the Xerces library. Ensure that you have the correct version of xercesImpl in your pom.xml.

<dependency>
    <groupId>xerces</groupId>
    <artifactId>xercesImpl</artifactId>
    <version>2.12.2</version> <!-- Use the latest stable version -->
</dependency>

Step 2: Exclude Conflicting Dependencies

Sometimes, older versions of Xerces or conflicting dependencies can cause issues. Ensure that there are no conflicting versions of Xerces in your dependency tree. You can use the mvn dependency:tree command to inspect your dependencies.

For example, exclude Xerces from other dependencies if necessary:

<dependency>
    <groupId>some.group</groupId>
    <artifactId>some-artifact</artifactId>
    <exclusions>
        <exclusion>
            <groupId>xerces</groupId>
            <artifactId>xercesImpl</artifactId>
        </exclusion>
    </exclusions>
</dependency>

Step 3: Update Spring and Related Dependencies

Since you’re migrating to JDK 17, ensure that all your dependencies are compatible with JDK 17. Update your Spring Boot and Spring Framework versions to the latest stable releases.

For example:

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.7.13</version> <!-- Use the latest stable version -->
</parent>

Step 4: Verify Classpath

Ensure that the xercesImpl JAR is included in your runtime classpath. If you’re running the application from an IDE, check the build configuration. If you’re using a packaged JAR (e.g., spring-boot:repackage), ensure that the dependency is included in the final JAR.

Step 5: Use JDK 17-Compatible Libraries

Some older libraries may not be fully compatible with JDK 17. Replace outdated libraries with their modern equivalents. For example:

• Replace javax.xml.bind (JAXB) with jakarta.xml.bind if you’re using JAXB.
• Ensure that all dependencies are compatible with JDK 17.

Updated pom.xml Example

Here’s an example of how your pom.xml might look after applying the fixes:

<dependencies>
    <!-- Other dependencies -->
    <dependency>
        <groupId>xerces</groupId>
        <artifactId>xercesImpl</artifactId>
        <version>2.12.2</version>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <!-- Add other dependencies as needed -->
</dependencies>

Common Pitfalls to Avoid

1. Using Outdated Libraries: Ensure that all libraries are compatible with JDK 17.
2. Conflicting Versions: Use the mvn dependency:tree command to identify and resolve version conflicts.
3. Missing Dependencies: Double-check that all required dependencies are included in the pom.xml.

Conclusion

The java.lang.NoClassDefFoundError: org/w3c/dom/ls/DocumentLS error is a common issue during JDK 11 to JDK 17 migration, especially in applications that rely on XML parsing. By adding the xercesImpl dependency, excluding conflicting libraries, and ensuring compatibility with JDK 17, you can resolve this issue and ensure a smooth migration.

If you found this post helpful, share it with your team or fellow developers. For more tips on Spring Boot, JDK migration, and troubleshooting, stay tuned!

Keywords

• Fix NoClassDefFoundError in JDK 17
• org/w3c/dom/ls/DocumentLS error in Spring Boot
• JDK 11 to JDK 17 migration issues
• XercesImpl dependency for XML parsing
• Spring Boot XML configuration error
• Java DOM Level 3 Load and Save (LS) module
• Resolve DocumentLS class not found
• JDK 17 compatibility issues
• Spring Boot JDK migration guide

By following these steps, you can resolve the NoClassDefFoundError and ensure your application runs smoothly on JDK 17. Happy coding! 🚀