Undertow

Definition

Undertow is an open-source, lightweight Java web server built by Red Hat that provides both blocking servlet-based and non-blocking asynchronous request handling through a composable set of handlers. It serves as the default embedded web server in WildFly and is offered as an alternative embedded server in Spring Boot applications, aimed at developers who want a smaller memory footprint and finer control over the request-processing pipeline than a traditional servlet container provides.

Overview

Undertow was created by Red Hat as the web layer for WildFly, the successor to JBoss Application Server, with a design goal of minimizing overhead so the same core could serve both a full Jakarta EE application server and a standalone microservice. Unlike Tomcat, which was built around the servlet API from the outset, Undertow was designed handler-first: the servlet implementation is layered on top of a lower-level, protocol-agnostic HTTP handler chain, so applications that do not need servlets can bypass that layer entirely and work directly with the lightweight core. Mechanically, an Undertow server is assembled from composable handlers, small units that each perform one task such as routing, authentication, or compression, chained together programmatically rather than declared in an XML deployment descriptor. This handler chain can operate in a fully non-blocking mode using Java NIO, allowing a small number of I/O threads to service many concurrent connections, or it can dispatch to a worker thread pool for blocking servlet code when full Jakarta EE compatibility is required. This dual-mode design lets a single server support both legacy blocking applications and newer reactive-style handlers. Against its peers, Undertow trades some of Tomcat's configuration familiarity and community tooling for a smaller footprint and a more programmable core, positioning it between Tomcat's servlet-centric design and Netty's fully low-level networking API. It is less commonly the default choice for greenfield projects than Tomcat, but it is the natural pick for teams already standardized on WildFly or Red Hat's middleware stack, and Spring Boot supports it as a drop-in replacement for Tomcat with minimal configuration change. In practice, Undertow shows up most often inside WildFly deployments in enterprises running Red Hat's Jakarta EE stack, and as an embedded server option for Spring Boot applications that need lower memory usage, such as services running many small instances in containers. Its programmatic handler API also appeals to developers building custom proxies or gateways who want fine control over request handling without the ceremony of a full servlet container. Undertow's main limitation is ecosystem size: its community, documentation, and third-party tooling are smaller than Tomcat's, so troubleshooting less common issues can take longer, and some servlet-based libraries assume Tomcat-specific extensions that Undertow does not replicate exactly. Teams already comfortable with Tomcat's configuration model and tooling often see limited benefit from switching unless memory footprint or handler-level customization is a specific requirement, and troubleshooting an unfamiliar handler-based configuration model can slow down operators who expect Tomcat's more conventional server.xml layout, extending the time needed to diagnose unfamiliar production issues.

Key Features

• Composable handler chain instead of XML-based servlet configuration
• Supports both blocking servlet mode and non-blocking NIO mode
• Serves as the default embedded web server in WildFly
• Available as a drop-in embedded server alternative in Spring Boot
• Small memory footprint suited to containerized microservices
• Programmatic API for building custom handlers and request pipelines
• Implements the Jakarta Servlet and WebSocket specifications
• Built and maintained by Red Hat as part of its middleware stack

Use Cases

Alternatives

Frequently Asked Questions

Related in Web