Spring Boot "ApplicationContextException: Unable to start web server" in CI

By Daniel Zoghalchali·Latchkey

Spring refreshed the context up to the web-server phase and initialization of the embedded server failed. The nested "Caused by" (a bind error, a missing bean, a servlet init failure) is the real cause.

What this error means

Startup fails with "ApplicationContextException: Unable to start web server; nested exception is ...", commonly wrapping a Tomcat connector or port error.

org.springframework.context.ApplicationContextException: Unable to start web server;
nested exception is org.springframework.boot.web.server.WebServerException: Unable to
start embedded Tomcat

Common causes

The server cannot bind its port

A port conflict or a privileged port the runner user cannot bind stops the connector from starting.

A servlet or filter bean fails to initialize

A ServletContextInitializer or filter throws during startup, aborting the web-server phase.

How to fix it

Read the nested WebServerException

1. Open the "nested exception is ..." line to see the concrete failure.
2. If it is a bind error, use a random or free port; if a bean, fix that bean.
3. Re-run and confirm the context refreshes past the web-server phase.

Avoid a fixed port in CI tests

Bind a random port so port conflicts cannot abort startup.

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)

How to prevent it

• Use random ports for web integration tests.
• Do not bind privileged ports (below 1024) as a non-root runner user.
• Read the nested WebServerException to distinguish bind from bean failures.

Frequently asked questions

Related guides

References

• Apache Maven guides
• Gradle user manual
• GitHub Actions documentation