Skip to content
javahacks.dev
Jakarta EE

Fix javax to jakarta ClassNotFoundException After Upgrading

Fix ClassNotFoundException for javax or jakarta classes after upgrading Spring Boot or a server by finding the library or container on the wrong namespace.

6 min read
Summarize in AI
Flat illustration of a request passing through a servlet container, with the Spring Boot, Spring, Apache Tomcat and Docker logos.

You upgrade to Spring Boot 3 or 4, or move a WAR to a new Tomcat, and the application dies on startup:

Text
java.lang.ClassNotFoundException: javax.servlet.Filter

or its mirror image, after a half-finished migration:

Text
java.lang.NoClassDefFoundError: jakarta/servlet/http/HttpServletRequest

Both mean the same thing. Something on your classpath was compiled against one namespace and the platform provides the other. Jakarta EE 9 renamed every package from javax.* to jakarta.*, and the two are not compatible at the bytecode level, so a library built for the old names cannot call a container that offers the new ones. This post finds the offending jar in four steps, shows how to fix it for Maven and Gradle, and lists the packages that should stay javax. Examples use Spring Boot 4, Tomcat 11 and Java 25.

Step 1: which namespace does your platform provide?

Decide the target before touching dependencies. The namespace follows the platform version, not your wishes.

PlatformNamespace
Spring Boot 2.x, Spring Framework 5javax.*
Spring Boot 3.x and 4.x, Spring Framework 6 and 7jakarta.*
Tomcat 9 and older, Jetty 10 and olderjavax.*
Tomcat 10.1 and 11, Jetty 11 and newerjakarta.*
WildFly up to 26javax.*
WildFly 27 and newerjakarta.*

The rule is about the whole stack. A Spring Boot 4 application cannot use a servlet container that still speaks javax, and a Tomcat 9 deployment cannot host a Spring Boot 3 WAR. Check what you are running:

Shell
java -jar target/app.jar --version 2>/dev/null | head -1
unzip -p target/app.jar META-INF/MANIFEST.MF | grep -i -E 'Spring-Boot-Version|Start-Class'

For an external server, read its RELEASE-NOTES or version.sh. The history of the rename and what it affected is in the Java EE to Jakarta EE namespace change.

Step 2: find the library that is on the old namespace

The stack trace names a class, not the jar that wanted it. Find who needs it. With Maven:

Shell
mvn dependency:tree -Dincludes=javax.servlet,javax.persistence,javax.validation,javax.annotation
Text
[INFO] dev.javahacks:shop:jar:1.0.0
[INFO] \- com.legacy:report-engine:jar:2.3.1:compile
[INFO]    \- javax.servlet:javax.servlet-api:jar:4.0.1:provided

Here report-engine 2.3.1 still depends on the javax servlet API. With Gradle:

Shell
./gradlew dependencyInsight --dependency javax.servlet-api --configuration runtimeClasspath

When the dependency is hidden inside a fat jar and is not declared, search the classes for references to the old package:

Shell
for j in lib/*.jar; do
  unzip -l "$j" | grep -q 'javax/servlet' && echo "$j has javax/servlet classes"
done

That finds jars that bundle the old API. For jars that merely call it, scan their bytecode strings:

Shell
for j in lib/*.jar; do
  unzip -p "$j" '*.class' 2>/dev/null | grep -a -q 'javax/servlet' && echo "$j references javax/servlet"
done

The nearest-wins resolution rules can also pick an old transitive version over the one you declared; how Maven mediates dependency versions explains why the tree shows what it shows.

Step 3: upgrade to the Jakarta release

Most active libraries publish a release line on jakarta. Look for a major version bump in the project's release notes, and upgrade.

LibraryLast javax lineFirst jakarta line
Hibernate ORM5.66.0
Hibernate Validator6.27.0
Jackson (JAX-RS and others)jackson-jaxrs 2.xjackson-jakarta-rs 2.13
Thymeleaf Spring integrationthymeleaf-spring5thymeleaf-spring6
Spring Security5.x6.x
Jersey2.x3.x

Example: a Hibernate 5 hibernate-core on a Spring Boot 4 project fails because Spring Data JPA 4 expects jakarta.persistence.EntityManager:

pom.xmlXML
<!-- Wrong: the 5.x line uses javax.persistence -->
<dependency>
    <groupId>org.hibernate</groupId>
    <artifactId>hibernate-core</artifactId>
    <version>5.6.15.Final</version>
</dependency>

<!-- Right: let the Spring Boot BOM pick the version -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>

Your own code needs the same treatment. Change the imports, which is mechanical:

Shell
grep -rl 'import javax\.\(servlet\|persistence\|validation\|ws\.rs\|annotation\.\(PostConstruct\|PreDestroy\|Resource\)\)' src \
  | xargs sed -i.bak -E 's/import javax\.(servlet|persistence|validation|ws\.rs)/import jakarta.\1/; s/import javax\.annotation\.(PostConstruct|PreDestroy|Resource)/import jakarta.annotation.\1/'

Review the diff before committing. For a larger codebase the OpenRewrite recipe org.openrewrite.java.migrate.jakarta.JavaxMigrationToJakarta handles imports, persistence.xml, web.xml and Maven coordinates together, and the manual route is documented in migrating javax to jakarta by hand. If a library has no Jakarta release and cannot be replaced, the Eclipse Transformer can rewrite its jar at build time, which works but leaves you owning a patched binary. The official walkthrough is the Spring Boot 3.0 migration guide.

Do not forget the non-Java files. These still carry old names and fail at runtime:

Shell
grep -rn 'javax\.' src/main/resources src/main/webapp --include=*.xml --include=*.properties --include=*.factories --include=*.imports

Typical hits are persistence.xml properties such as javax.persistence.jdbc.url (now jakarta.persistence.jdbc.url), web.xml schema locations and META-INF/services files.

Step 4: remove the old API from the classpath

A jar that bundles the old API can shadow or conflict with the new one. Exclude it:

pom.xmlXML
<dependency>
    <groupId>com.legacy</groupId>
    <artifactId>report-engine</artifactId>
    <version>3.0.0</version>
    <exclusions>
        <exclusion>
            <groupId>javax.servlet</groupId>
            <artifactId>javax.servlet-api</artifactId>
        </exclusion>
    </exclusions>
</dependency>

And make sure your own build does not add the old API for compilation. A provided dependency on javax.servlet-api left over in a parent POM will make the IDE happy while the runtime fails. Search every pom.xml and build.gradle.kts for javax. coordinates.

Then rebuild clean and verify nothing references the old names in your output:

Shell
mvn clean package
unzip -p target/app.jar 'BOOT-INF/classes/**' | grep -a -c 'javax/servlet'
Text
0

For a Spring Boot application, the overall upgrade steps and the checks that surround this one are in the Spring Boot guide from first project to production.

Confirm which jar the JVM actually loaded

The dependency tree shows what the build resolved, and the runtime can differ, especially in an application server where the container adds its own libraries. Ask the JVM where a class came from by logging class loading for the failing package:

Shell
java -Xlog:class+load:file=classload.log -jar target/app.jar
grep -E 'javax/(servlet|persistence)' classload.log | head -3
Text
[0.812s][info][class,load] javax.servlet.Filter source: jar:file:/app/lib/report-engine-2.3.1.jar!/javax/servlet/Filter.class

The source: field names the jar that supplied the class, which is the one to upgrade or exclude. If the grep prints nothing and the application still fails, the class is loaded lazily on the failing request, so trigger that request first. On an external Tomcat, do the same with CATALINA_OPTS, and remember that a WAR copied into a server that provides the other namespace needs the server upgraded or the WAR rebuilt, whichever matches your Step 1 decision.

Packages that stayed javax

Not everything was renamed, and renaming too much produces the opposite error. The JDK's own packages are untouched: javax.sql, javax.crypto, javax.net, javax.net.ssl, javax.naming, javax.security.auth, javax.xml (JAXP), javax.script, javax.management, javax.imageio, javax.swing, javax.tools. A blind find-and-replace of javax. to jakarta. breaks every one of these with a compile error such as package jakarta.sql does not exist. Rename only the packages that moved with Jakarta EE: servlet, persistence, validation, transaction, mail, ws.rs, inject, annotation (the common annotations), websocket, json and the like. The list is in the Jakarta EE specifications index.

Where this does not apply

If the missing class is in a package that exists in neither namespace, such as javax.xml.bind, the cause is different: JAXB left the JDK in Java 11 and needs jakarta.xml.bind-api plus a runtime like jaxb-runtime. If the error shows only in a test, check test-scoped dependencies and the surefire classpath, which the tree command shows with -Dscope=test. And if you are deliberately staying on Boot 2.7 for now, the fix is the opposite one: pin every library to its javax line and do not mix the two.

Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.