Why Spring Boot 4.0 Dropped Undertow and How to Migrate Your Projects

Background

Spring Boot historically supports three embedded web containers: Tomcat (default), Jetty, and Undertow. Undertow was chosen for its low memory usage and high throughput in high‑concurrency scenarios.

Why Undertow was removed in Spring Boot 4.0

The core reason is the adoption of Servlet 6.1 in Spring Framework 7, which Spring Boot 4.0 depends on. Undertow has not yet been adapted to Servlet 6.1, and its maintainer Red Hat has limited resources, making timely compatibility unlikely.

“Spring Boot 4.0 needs a Servlet 6.1 baseline, and Undertow is currently incompatible. Therefore we drop support for Undertow.”

The Spring Boot team opened issue #46917 to track the change and noted that the Undertow community has started work on a 2.4.0.Alpha1 release (targeting Jakarta EE 11) but no concrete timeline.

What Servlet 6.1 introduces

ByteBuffer support in ServletInputStream and ServletOutputStream (example code shown).

HTTP/2 server‑push removal .

Removal of SecurityManager‑related APIs .

Enhanced HTTP session handling for WebSocket scenarios.

More granular HTTP‑redirect control .

Sensitive request‑header security method HttpServlet.isSensitiveHeader.

Impact on existing projects

Projects that depend on spring-boot-starter-undertow will fail to start with an error such as:

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

Three main risks are:

Startup failure due to missing Undertow implementation.

Configuration loss – any server.undertow.* settings are ignored.

Potential performance regression after switching containers, requiring re‑benchmarking.

Migration options

Option 1 – Switch to Tomcat (recommended)

Remove the Undertow dependency.

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

Convert Undertow configuration to Tomcat equivalents, e.g.:

# 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 spring-boot-starter-jetty and exclude the default Tomcat.

Jetty fully supports Servlet 6.1 and performs well in I/O‑intensive workloads.

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jetty</artifactId>
</dependency>
<!-- Exclude Tomcat to avoid conflict -->
<exclusions>
    <exclusion>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-tomcat</artifactId>
    </exclusion>
</exclusions>

Supported container versions in Spring Boot 4.0

Tomcat 11.0.x – ✅ supported (default).

Jetty 12.1.x – ✅ supported.

Undertow – ❌ removed.

Pros and cons of Tomcat vs Jetty

Ecology maturity : Tomcat ★★★★★, Jetty ★★★★.

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

Default inclusion : Tomcat ✅, Jetty ❌ (manual).

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

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

Recommendations

For most projects, switch back to Tomcat because it is the default, most mature, and fully compatible with Servlet 6.1. Choose Jetty only for I/O‑heavy applications where its performance edge matters.

If you are still on Spring Boot 3.x, you may keep Undertow but should start planning migration. New projects should start with Tomcat (or Jetty) directly.

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