Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

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.

~5 min readJava
#Spring Boot#Jakarta EE#Maven#Migration
A servlet container gate splitting javax and jakarta plates, red on the old side, headline JAVAX TO JAKARTA

Introduction & Quick Summary

Symptom. After moving to Spring Boot 4, the application starts and the first request that touches a servlet API fails:

code
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.

bash
mvn dependency:tree -Dincludes=javax.servlet,javax.persistence,javax.validation,javax.annotation
xml
<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:

bash
# 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' | head

An 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:

java
@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

StackServlet namespaceTypical container
Spring Boot 2.x, Spring Framework 5javax.*Tomcat 9
Spring Boot 3.x, Spring Framework 6jakarta.*Tomcat 10.1
Spring Boot 4.x, Spring Framework 7jakarta.*, Servlet 6.1Tomcat 11
Jakarta EE 9 containersjakarta.*GlassFish 6, WildFly 27
Jakarta EE 8 and earlierjavax.*WildFly 26, Tomcat 9
ErrorMeaningWhere to look
NoClassDefFoundError: javax/servlet/http/HttpServleta library needs the old APIdependency tree, then upgrade the library
ClassNotFoundException: javax.xml.bind.DatatypeConverterJAXB was removed from the JDKadd jakarta.xml.bind-api and an implementation
NoSuchMethodError on a Spring classtwo Spring versions on the classpathdependency tree for spring-core
ClassNotFoundException: jakarta.servlet.* in a WARdeployed to a javax containerTomcat 10.1 or newer
IllegalArgumentException: Not a managed typeJPA entities from a javax jarexclude 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:

bash
mvn dependency:tree -Dincludes=javax.servlet,javax.persistence,javax.validation,javax.annotation ./gradlew dependencyInsight --dependency javax.servlet-api --configuration runtimeClasspath

If the dependency is a fat jar that bundles classes rather than declaring them, search the archives:

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

A 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:

xml
<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:

xml
<!-- 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:

bash
$CATALINA_HOME/bin/version.sh | grep "Server version" unzip -p target/app.war WEB-INF/lib/*.jar 2>/dev/null | head

5. 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.

bash
# inspect what a jar actually references before trusting it unzip -p lib/legacy.jar com/legacy/Report.class | strings | grep -i "javax/servlet" | sort -u

6. 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-api to "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. provided and test scopes fail later.
  • Setting java.version to 11 in pom.xml while 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 @SpringBootTest on 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 documentation

The Java documentation that defines the behaviour this guide explains.

Try matching browser tools

All tools

Small utilities that fit Java work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Java guides

More in Java

All Java guides

The guides filed next to this one in Java, in library order.