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.

You upgrade to Spring Boot 3 or 4, or move a WAR to a new Tomcat, and the application dies on startup:
java.lang.ClassNotFoundException: javax.servlet.Filteror its mirror image, after a half-finished migration:
java.lang.NoClassDefFoundError: jakarta/servlet/http/HttpServletRequestBoth 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.
| Platform | Namespace |
|---|---|
| Spring Boot 2.x, Spring Framework 5 | javax.* |
| Spring Boot 3.x and 4.x, Spring Framework 6 and 7 | jakarta.* |
| Tomcat 9 and older, Jetty 10 and older | javax.* |
| Tomcat 10.1 and 11, Jetty 11 and newer | jakarta.* |
| WildFly up to 26 | javax.* |
| WildFly 27 and newer | jakarta.* |
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:
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:
mvn dependency:tree -Dincludes=javax.servlet,javax.persistence,javax.validation,javax.annotation[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:providedHere report-engine 2.3.1 still depends on the javax servlet API. With Gradle:
./gradlew dependencyInsight --dependency javax.servlet-api --configuration runtimeClasspathWhen the dependency is hidden inside a fat jar and is not declared, search the classes for references to the old package:
for j in lib/*.jar; do
unzip -l "$j" | grep -q 'javax/servlet' && echo "$j has javax/servlet classes"
doneThat finds jars that bundle the old API. For jars that merely call it, scan their bytecode strings:
for j in lib/*.jar; do
unzip -p "$j" '*.class' 2>/dev/null | grep -a -q 'javax/servlet' && echo "$j references javax/servlet"
doneThe 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.
| Library | Last javax line | First jakarta line |
|---|---|---|
| Hibernate ORM | 5.6 | 6.0 |
| Hibernate Validator | 6.2 | 7.0 |
| Jackson (JAX-RS and others) | jackson-jaxrs 2.x | jackson-jakarta-rs 2.13 |
| Thymeleaf Spring integration | thymeleaf-spring5 | thymeleaf-spring6 |
| Spring Security | 5.x | 6.x |
| Jersey | 2.x | 3.x |
Example: a Hibernate 5 hibernate-core on a Spring Boot 4 project fails because Spring Data JPA 4 expects jakarta.persistence.EntityManager:
<!-- 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:
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:
grep -rn 'javax\.' src/main/resources src/main/webapp --include=*.xml --include=*.properties --include=*.factories --include=*.importsTypical 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:
<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:
mvn clean package
unzip -p target/app.jar 'BOOT-INF/classes/**' | grep -a -c 'javax/servlet'0For 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:
java -Xlog:class+load:file=classload.log -jar target/app.jar
grep -E 'javax/(servlet|persistence)' classload.log | head -3[0.812s][info][class,load] javax.servlet.Filter source: jar:file:/app/lib/report-engine-2.3.1.jar!/javax/servlet/Filter.classThe 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.


