How to Resolve "Web application could not be started as there was no org.springframework.boot.web.servlet.server.ServletWebServerFactory bean defined in the context" Issue

Introduction

When developing a Spring Boot web application, you might encounter an error message stating:

Web application could not be started as there was no org.springframework.boot.web.servlet.server.ServletWebServerFactory bean defined in the context.

This error occurs when Spring Boot cannot find a ServletWebServerFactory bean, which is essential for starting the embedded web server. One of the common reasons for this issue is a missing @SpringBootApplication annotation. This blog post will explain the causes of this issue, with a focus on the missing annotation, and provide solutions to resolve it.

Causes

The error typically occurs for one of the following reasons:

1. Missing @SpringBootApplication Annotation: The most common cause is the absence of the @SpringBootApplication annotation on your main application class.
2. Missing Spring Boot Starter Web Dependency: Another common cause is the absence of the spring-boot-starter-web dependency in your project.
3. Incorrect Application Type: Your application might be configured as a non-web application.
4. Custom Configuration Issues: Custom configurations might inadvertently exclude the necessary web server beans.
5. Exclusion of Embedded Web Server: You might have excluded the embedded web server dependency from your build configuration.

Solutions

1. Adding the @SpringBootApplication Annotation

Ensure that your main application class is annotated with @SpringBootApplication. This annotation is a combination of @Configuration, @EnableAutoConfiguration, and @ComponentScan, which are essential for bootstrapping a Spring Boot application.

Example:

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class MyApplication {

    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

2. Adding the Spring Boot Starter Web Dependency

Ensure that your pom.xml (for Maven) or build.gradle (for Gradle) file includes the spring-boot-starter-web dependency.

Maven:

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

Gradle:

implementation 'org.springframework.boot:spring-boot-starter-web'

3. Checking the Application Type

Ensure that your application is configured as a web application. In Spring Boot, this is typically inferred from the presence of spring-boot-starter-web.

If you have explicitly configured the application type, make sure it is set correctly:

@SpringBootApplication
public class MyApplication {

    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

4. Reviewing Custom Configurations

Review your custom configurations to ensure they do not exclude the ServletWebServerFactory bean.

For example, if you have custom configuration classes, ensure they are not excluding necessary auto-configurations:

@Configuration
public class CustomConfig {
    // Ensure necessary configurations are included
}

5. Ensuring Embedded Web Server is Included

If you have intentionally or unintentionally excluded the embedded web server, you need to include it back. Check your pom.xml or build.gradle for any exclusions:

Maven:

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

Remove the exclusion if you want to use the embedded Tomcat server:

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

6. Using a Different Web Server

If you prefer using a different embedded web server (e.g., Jetty or Undertow), ensure you have included the correct dependency:

Maven (Jetty):

<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>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jetty</artifactId>
</dependency>

Gradle (Jetty):

implementation('org.springframework.boot:spring-boot-starter-web') {
    exclude group: 'org.springframework.boot', module: 'spring-boot-starter-tomcat'
}
implementation 'org.springframework.boot:spring-boot-starter-jetty'

7. Enabling Auto-Configuration

Ensure that auto-configuration is enabled. This is the default behavior, but it can be disabled accidentally. Check your application configuration:

@SpringBootApplication
public class MyApplication {

    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

If you have disabled specific auto-configurations, make sure to re-enable the necessary ones:

@SpringBootApplication(exclude = {
    // Exclude specific auto-configurations if necessary
})
public class MyApplication {

    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

Conclusion

The error "Web application could not be started as there was no org.springframework.boot.web.servlet.server.ServletWebServerFactory bean defined in the context" typically occurs due to missing dependencies, incorrect application type, custom configuration issues, or exclusions of the embedded web server. One of the most common causes is the absence of the @SpringBootApplication annotation on the main application class. By following the steps outlined in this blog post, you can resolve this issue and ensure your Spring Boot web application starts successfully.

If you continue to encounter issues, consult the official Spring Boot documentation for further guidance and troubleshooting tips.