Spring Boot 4: NoClassDefFoundError javax/servlet/http/HttpServlet
Spring Boot 4 runs Jakarta only. A library compiled against javax asks for a class that no longer exists, and the stack trace hides which jar.

Introduction & Quick Summary
Symptom. After moving to Spring Boot 4, the application starts and the first request that touches a servlet API fails:
java.lang.NoClassDefFoundError: javax/servlet/http/HttpServlet
at org.springframework.web.servlet.FrameworkServlet.initServletBean(FrameworkServlet.java:...)
Caused by: java.lang.ClassNotFoundException: javax.servlet.http.HttpServlet
at java.base/jdk.internal.loader.BuiltinClassLoader.loadClass(BuiltinClassLoader.java:...)The same shape appears for javax/servlet/ServletRequest, javax/servlet/http/HttpServletRequest, javax/validation/Validation and javax/persistence/EntityManager. Tests fail at MockMvcBuilders.standaloneSetup(...) even though the application code imports nothing from javax at all.
Cause. Spring Boot 4 is built on Spring Framework 7, Jakarta EE 11 and a Servlet 6.1 baseline, so the runtime only provides jakarta.*. A dependency on the classpath was compiled against the old javax.* packages and is asking for a class that no longer exists anywhere in the runtime. The stack trace names the class, not the jar that wanted it.
Fix. Find the jar, then upgrade it or exclude the old API it drags in.
mvn dependency:tree -Dincludes=javax.servlet,javax.persistence,javax.validation,javax.annotation<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>Core Mechanics, Signatures & Reproducible Setup
Jakarta EE renamed packages from javax.* to jakarta.*, and a rename is a binary change: javax.servlet.http.HttpServlet and jakarta.servlet.http.HttpServlet are different classes with different names, so one cannot satisfy a reference to the other. Spring Boot 4 requires Java 17 or later, Jakarta EE 11, Servlet 6.1, and Spring Framework 7, which means the container and every library in the servlet path must speak the new namespace.
Decide the target before touching dependencies. The namespace follows the platform, not preference:
# what am I actually running
unzip -p target/app.jar META-INF/MANIFEST.MF | grep -E 'Spring-Boot-Version|Start-Class'
mvn -q dependency:tree | grep -E 'spring-boot|spring-webmvc' | headAn application on Boot 3.x is already on jakarta; the failure there comes from a library, not from the framework. An application jumping from Boot 2.x to 4 has both problems at once: its own imports and its libraries.
Reproduce the failure in a test so the diagnosis is not tied to a running container:
@Test
void servletApiIsJakarta() {
assertThrows(ClassNotFoundException.class,
() -> Class.forName("javax.servlet.http.HttpServlet"));
assertDoesNotThrow(() -> Class.forName("jakarta.servlet.http.HttpServlet"));
}That test is a useful canary: it fails precisely when something puts the old API back on the classpath.
Key Comparison Table
| Stack | Servlet namespace | Typical container |
|---|---|---|
| Spring Boot 2.x, Spring Framework 5 | javax.* | Tomcat 9 |
| Spring Boot 3.x, Spring Framework 6 | jakarta.* | Tomcat 10.1 |
| Spring Boot 4.x, Spring Framework 7 | jakarta.*, Servlet 6.1 | Tomcat 11 |
| Jakarta EE 9 containers | jakarta.* | GlassFish 6, WildFly 27 |
| Jakarta EE 8 and earlier | javax.* | WildFly 26, Tomcat 9 |
| Error | Meaning | Where to look |
|---|---|---|
NoClassDefFoundError: javax/servlet/http/HttpServlet | a library needs the old API | dependency tree, then upgrade the library |
ClassNotFoundException: javax.xml.bind.DatatypeConverter | JAXB was removed from the JDK | add jakarta.xml.bind-api and an implementation |
NoSuchMethodError on a Spring class | two Spring versions on the classpath | dependency tree for spring-core |
ClassNotFoundException: jakarta.servlet.* in a WAR | deployed to a javax container | Tomcat 10.1 or newer |
IllegalArgumentException: Not a managed type | JPA entities from a javax jar | exclude the old persistence API |
Practical Edge Cases, Error Fixes & Deep Dive Code Examples
1. Finding the jar, not the class
mvn dependency:tree with -Dincludes prints only the paths that matter, which is faster than reading four hundred lines:
mvn dependency:tree -Dincludes=javax.servlet,javax.persistence,javax.validation,javax.annotation
./gradlew dependencyInsight --dependency javax.servlet-api --configuration runtimeClasspathIf the dependency is a fat jar that bundles classes rather than declaring them, search the archives:
for j in lib/*.jar; do
unzip -l "$j" | grep -q 'javax/servlet' && echo "$j bundles javax/servlet";
doneA jar that bundles the old API usually also compiles against it, so an exclusion alone is not enough; the library needs a Jakarta-capable release.
2. Test libraries are the usual culprit
Test-scoped dependencies fail the build at test compile time or at runtime under MockMvc, which is why the application "works" and the pipeline does not. rest-assured's spring-mock-mvc module was compiled against javax and fails with exactly this error on Spring Framework 7; the fix is a release built for Jakarta, plus an exclusion of the transitive spring-webmvc 5.x it carries:
<dependency>
<groupId>io.rest-assured</groupId>
<artifactId>spring-mock-mvc</artifactId>
<version>6.0.1</version>
<scope>test</scope>
<exclusions>
<exclusion>
<groupId>org.springframework</groupId>
<artifactId>spring-webmvc</artifactId>
</exclusion>
</exclusions>
</dependency>Leaving the transitive Spring 5 on a test classpath reintroduces the old namespace through a dependency nobody declared, which is the hardest version of this to find later.
3. provided scope hides the failure until deployment
A javax.servlet-api dependency in provided scope compiles fine and fails at runtime, because the container supplies jakarta instead. Remove it rather than raising its version:
<!-- remove entirely; Boot manages the Jakarta API -->
<dependency>
<groupId>javax.servlet</groupId>
<artifactId>javax.servlet-api</artifactId>
<scope>provided</scope>
</dependency>If you genuinely manage the API yourself, use the matching Jakarta coordinates and let Boot manage the version when possible.
4. WAR deployments and container mismatch
A WAR built for jakarta cannot run on Tomcat 9, and a WAR built for javax cannot run on Tomcat 11. The error in the first case is a ClassNotFoundException: jakarta.servlet.* at startup. Check the target container before concluding the build is wrong:
$CATALINA_HOME/bin/version.sh | grep "Server version"
unzip -p target/app.war WEB-INF/lib/*.jar 2>/dev/null | head5. Third-party internals: the library simply is not ready
When a library has no Jakarta release, the practical options are an exclusion plus a fork, a package migration tool at build time, or isolating the dependency behind a separate service. A bytecode relocation is a transitional measure, and it needs the same test coverage as a code change: reflection, serialized classes and string-based configuration do not follow a rename the way compiled references do.
# inspect what a jar actually references before trusting it
unzip -p lib/legacy.jar com/legacy/Report.class | strings | grep -i "javax/servlet" | sort -u6. The smaller removals that arrive with the same upgrade
Boot 4 also needs Java 17 minimum and GraalVM 25 or later for native images, so a native-maven-plugin build fails with an older toolchain before any servlet class is loaded. Vintage engine and JUnit 4 style tests are gone from the default test stack, and spring-boot-starter-web now pulls Tomcat 11, which drops some legacy configuration valves. Read the migration guide's system requirements section first: a JDK 11 CI image fails earlier and more confusingly than any classpath issue.
Common Compilation/Runtime Mistakes & Version Gotchas
- Adding
javax.servlet-apito "fix" the error. It supplies the class the JVM cannot find, except that it does not — the missing class is in a jar that asked for it, and adding the API only hides a second failure. - Upgrading only your own imports. A library's bytecode is not rewritten by your
sed. - Trusting a green
mvn compile.providedand test scopes fail later. - Setting
java.versionto 11 inpom.xmlwhile CI has 17. The build passes locally and fails in the pipeline. - Ignoring test-only dependencies. The Jakarta migration breaks mock MVC setups first.
- Using
@SpringBootTeston a servlet stack after switching to WebFlux. Different starter, different classpath, unrelated error. - Skipping the migration guide for system requirements. Each major Boot release raises the floor for Java and GraalVM.
Check the HTTP status a downstream service returns while you debug the container with the status code reference, and compare the two dependency trees with the text diff tool instead of reading them line by line.
Reference: Spring Boot 4.0 migration guide and Jakarta Servlet 6.1 specification.
Official references
primary documentationThe Java documentation that defines the behaviour this guide explains.
Try matching browser tools
All toolsSmall utilities that fit Java work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Java guides
All Java guidesClassNotFoundException vs NoClassDefFoundError in Java
One is a missing lookup, the other a failed link or initialiser. The distinction decides whether you inspect a classpath or a stack trace.
Java: java.lang.OutOfMemoryError: Metaspace
Class metadata lives outside the heap. Which limit was hit, how to find the classloader that grows, and why a container restart with exit code 137 is the same disease.
UnsupportedClassVersionError: Class File Version 61 vs 65
Bytecode newer than the JVM fails before main runs. --release, not -source/-target, keeps the class version and the API surface in agreement.
Java Record Patterns: Deconstruction, Nested Records, and switch Syntax
How Java 21 record patterns deconstruct record values, how nested patterns compose, and how guards, ordering, and exhaustiveness decide whether a pattern switch compiles.
More in Java
All Java guidesThe guides filed next to this one in Java, in library order.