Why Spring Boot 4.0 Dropped Undertow and How to Migrate

Background

Spring Boot 4.0 is built on Spring Framework 7 and mandates the Servlet 6.1 baseline. Because Undertow has not been adapted to Servlet 6.1, Spring Boot 4.0 removes its support.

Why Undertow Was Originally Chosen

Tomcat – default, mature ecosystem, Spring Boot’s "child".

Jetty – lightweight, flexible, excels in some scenarios.

Undertow – low memory usage, high concurrent throughput, native persistent‑connection support.

Reasons for Removal

"Spring Boot 4.0 needs a Servlet 6.1 baseline, and Undertow is not yet compatible. Therefore we drop Undertow support."

Root cause: Servlet 6.1 incompatibility. Spring Boot 4.0 depends on Servlet 6.1, while Undertow has not been updated.

Deeper cause: Red Hat, the main maintainer of Undertow, invests limited resources, so the project cannot keep pace with the new specification. The Spring Boot team tracks the change in GitHub Issue #46917, where they note the high adaptation cost.

Additional non‑technical factors include a smaller community, less documentation, and incomplete support for the traditional Servlet model.

What Servlet 6.1 Brings

ByteBuffer support in ServletInputStream and ServletOutputStream for better non‑blocking I/O.

HTTP/2 Server Push is deprecated.

SecurityManager‑related APIs are removed.

Enhanced HTTP session mechanisms, especially for WebSocket use cases.

More granular control over HTTP redirects.

Sensitive‑header detection via HttpServlet.isSensitiveHeader.

ByteBuffer buffer = ByteBuffer.allocate(1024);
servletInputStream.read(buffer);

Impact on Existing Projects

Typical Error

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-undertow</artifactId>
</dependency>

After upgrading to Spring Boot 4.0 the application fails to start with:

Caused by: java.lang.IllegalStateException: Unable to find Undertow-based WebServer implementation.

Risks

Startup failure: Missing Undertow implementation prevents the app from launching.

Configuration loss: All server.undertow.* settings are ignored.

Performance regression: Switching containers requires re‑benchmarking and tuning.

Migration Options

Option 1 – Switch to Tomcat (recommended)

Remove the Undertow starter dependency (comment it out).

Tomcat is included by default via spring-boot-starter-web.

Convert Undertow‑specific configuration to Tomcat equivalents.

# Old Undertow config
server:
  undertow:
    io-threads: 4
    worker-threads: 20
    buffer-size: 1024

# New Tomcat config
server:
  tomcat:
    threads:
      max: 200
      min-spare: 10
    max-connections: 8192

Option 2 – Use Jetty

Add the Jetty starter and exclude Tomcat to avoid conflicts.

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-jetty</artifactId>
</dependency>

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-web</artifactId>
  <exclusions>
    <exclusion>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-tomcat</artifactId>
    </exclusion>
  </exclusions>
</dependency>

Supported Container Versions in Spring Boot 4.0

Tomcat 11.0.x – Servlet 6.1 – ✅ supported.

Jetty 12.1.x – Servlet 6.1 – ✅ supported.

Undertow – not compatible – ❌ removed.

Benefits of Dropping Undertow

Alignment with Servlet 6.1 gives a clearer technology stack.

Reduces maintenance burden for the Spring Boot team.

Pressures the Undertow community to accelerate Servlet 6.1 support.

Ensures consistency with Jakarta EE 11.

Costs for Developers

Migration effort to Tomcat or Jetty.

Potential performance uncertainty if Undertow’s advantages were a key factor.

All server.undertow.* settings must be rewritten.

Short‑term pain for projects that rely heavily on Undertow‑specific features.

Recommendations & Scenarios

If you are upgrading to Spring Boot 4.0, switch to Tomcat or Jetty before the upgrade.

If you remain on Spring Boot 3.x, you can keep Undertow but should start planning migration.

For new projects, use Tomcat (default) or Jetty; avoid Undertow.

Tomcat vs Jetty Comparison

Ecosystem maturity: Tomcat ★★★★★, Jetty ★★★★.

Documentation richness: Tomcat ★★★★★, Jetty ★★★★.

Default support: Tomcat ✅, Jetty requires manual inclusion ❌.

I/O‑intensive workloads: Jetty ★★★★★, Tomcat ★★★★.

Enterprise‑grade features: Tomcat ★★★★★, Jetty ★★★★.

Conclusion

Spring Boot 4.0 drops Undertow not because the Spring team dislikes it, but because Undertow cannot keep up with the Servlet 6.1 evolution and lacks sufficient upstream investment. Migration to Tomcat (the default) or Jetty is straightforward, and future Undertow support will depend on its ability to adapt to Servlet 6.1.

Official Resources

Spring Boot 4.0 Migration Guide – https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Migration-Guide

Spring Boot 4.0 Release Notes – https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Release-Notes