How to Fix NoClassDefFoundError: javax/xml/bind/DatatypeConverter in Java (Java 11+)

While upgrading Java applications from Java 8 to Java 11 or later, many developers encounter the following runtime error:

Caused by: java.lang.NoClassDefFoundError: javax/xml/bind/DatatypeConverter

This issue is very common in Spring Boot, microservices, JWT-based authentication, and SOAP/JAX-WS clients. The error occurs because certain Java EE modules were removed from the JDK starting with Java 9.

In this article, you’ll learn why this error happens, how to fix it correctly, and which solution is best for production applications.

Real-World Use Case

You may see this error when:

• Migrating a Spring Boot app from Java 8 → Java 11 and Later versions
• Running JWT authentication libraries
• Using SOAP or XML-based APIs
• Deploying microservices on Docker with Java 17

Even though your code compiles successfully, the application fails at runtime, making this issue confusing for many developers.

Why This Error Occurs

javax.xml.bind.DatatypeConverter belongs to JAXB (Java XML Binding).

Java Version Behavior

So when your application or dependency tries to load JAXB classes on Java 11+, the JVM throws:

NoClassDefFoundError

Solution 1: Add JAXB Dependency (Recommended)

This is the best and safest solution for Java 11, 17, and newer versions.

Maven Configuration

<dependency>
    <groupId>jakarta.xml.bind</groupId>
    <artifactId>jakarta.xml.bind-api</artifactId>
    <version>2.3.3</version>
</dependency>

<dependency>
    <groupId>org.glassfish.jaxb</groupId>
    <artifactId>jaxb-runtime</artifactId>
    <version>2.3.3</version>
</dependency>

Gradle Configuration

implementation 'jakarta.xml.bind:jakarta.xml.bind-api:2.3.3'
implementation 'org.glassfish.jaxb:jaxb-runtime:2.3.3'

✅ Works with Java 11, 17, 21
✅ Production-safe
✅ Recommended for Spring Boot & Microservices

Solution 2: Replace DatatypeConverter Usage (Best Practice)

If your own code is using DatatypeConverter, you can remove JAXB completely.

❌ Old Code (JAXB)

DatatypeConverter.printBase64Binary(bytes);

✅ New Code (Java Built-in)

import java.util.Base64;String encoded = Base64.getEncoder().encodeToString(bytes);

Decode Example

byte[] decoded = Base64.getDecoder().decode(encoded);

✅ No external dependency
✅ Cleaner and faster
✅ Future-proof

Libraries That Commonly Cause This Error

• JWT libraries (io.jsonwebtoken)
• SOAP / JAX-WS clients
• Older Jackson XML modules
• Legacy Spring Boot projects

Best Practices & Recommendations

✔ Prefer dependency-based solution for Java 11+
✔ Replace JAXB APIs if only Base64 functionality is needed

Summary

In this tutorial, you learned:

• Why NoClassDefFoundError: javax/xml/bind/DatatypeConverter occurs
• How Java removed JAXB after Java 8
• Two proven solutions to fix the issue
• Best practices for modern Java applications

If you’re upgrading Java versions, this fix will save you hours of debugging time.

FAQs