SoFunction
Updated on 2025-04-13

The ultimate guide to troubleshooting and solving 11 high-frequency problems caused by SpringBoot startup errors

1. Dependency conflict: The ultimate solution to NoSuchMethodError

Error phenomenon:

:  

Cause analysis:

Different versions of Spring component conflicts (such as the existence of Spring Boot 2.3 and 2.5 dependencies).

Solution:

Maven project: Run dependency tree analysis command to locate conflicts:

mvn dependency:tree -Dverbose | grep conflict

Gradle project: Execution dependency report:

gradle dependencies >

Explicitly declare the version number in or, use <exclusions> to exclude old dependencies.

Pit prevention tips:

Use IDE plug-ins (such as IntelliJ's Maven Helper and VS Code's Gradle Lens) to visualize the analysis of dependency trees.

2. Bean injection failed: How to break No qualifying bean of type?

Error phenomenon:

No qualifying bean of type '' available  

Cause analysis:

  • No annotations such as @Component, @Service, etc. were added.
  • The package path is not scanned by @ComponentScan.
  • Bean's scope configuration is wrong (such as @Scope("prototype") causing delayed initialization).

Solution:

  • Check if the class has added Spring annotations.
  • Make sure that the package where the main class is located contains the paths to all beans (or manually specify @ComponentScan).
  • Use @Autowired(required = false) to avoid forced injection.

Code example:

@SpringBootApplication  
@ComponentScan(basePackages = "") // Explicitly specify the scan pathpublic class Application { ... }

3. Port occupancy: 3 solutions for Port 8080 already in use

Error phenomenon:

WebServerException: Unable to start embedded Tomcat (Port 8080 already in use)  

Solution:

Terminate the occupation process:

# Linux/Mac  
lsof -i :8080 && kill -9 <PID>  
# Windows  
netstat -ano | findstr 8080 && taskkill /F /PID <PID>

Modify the application port:

#   
server:  
  port: 8081

Random port (suitable for testing environment):

server:  
  port: 0

4. Configuration file failed to load: Why doesn't it take effect?

Error phenomenon:

The configuration properties are not effective and there are no errors reported in the log.

Cause analysis:

  • File name error (such as misspelling).
  • The file is not placed in the src/main/resources directory.
  • YAML syntax error (such as indentation inconsistency).

Solution:

  • Check whether the file name and path comply with Spring Boot specifications.
  • Verify syntax using YAML verification tools such as online YAML Parser.

Turn on configuration properties debugging:

logging:  
  level:  
    : TRACE

5. Database connection pool error: HikariPool-1 - Exception during pool initialization

Error phenomenon:

HikariPool-1 - Exception during pool initialization: Connection refused  

Cause analysis:

The database URL, username, or password is incorrect.

The database service is not started.

The connection pool configuration timeout time is too short.

Solution:

Check the database configuration:

spring:  
  datasource:  
    url: jdbc:mysql://localhost:3306/mydb?useSSL=false  
    username: root  
    password: root

Increase the connection pool timeout time:

spring:  
  datasource:  
    hikari:  
      connection-timeout: 30000

6. The main class is missing: The hidden reason for Unable to find main class

Error phenomenon:

Error: Unable to find or load main class  

Solution:

Maven project: Check whether the main class is configured:

<properties>  
    <start-class></start-class>  
</properties>

Gradle project: Specify the main class in:

springBoot {  
    mainClass = ''  
}

Regenerate the IDE project file (such as executing mvn idea:idea or gradle idea).

7. Requested bean is currently in creation

Error phenomenon:

BeanCurrentlyInCreationException: Error creating bean with name 'A'  

Solution:

Preferred constructor injection: Avoid field injection causing circular dependencies.

Lazy loading: Add @Lazy annotation on one of the beans.

The ultimate solution: refactor the code and extract public logic to third-party classes.

Code example:

@Service  
public class ServiceA {  
    private final ServiceB serviceB;  
    public ServiceA(@Lazy ServiceB serviceB) {  
         = serviceB;  
    }  
}

8. JAR package conflict: the precise positioning method of ClassNotFoundException

Error phenomenon:

: . 

Solution:

Check if the dependency is missing:

&lt;!-- MavenExample --&gt;  
&lt;dependency&gt;  
    &lt;groupId&gt;&lt;/groupId&gt;  
    &lt;artifactId&gt;commons-lang3&lt;/artifactId&gt;  
    &lt;version&gt;3.12.0&lt;/version&gt;  
&lt;/dependency&gt;

Use mvn clean install -U to force update dependencies.

Check for <scope>provided</scope> error configuration.

9. Cache configuration error: RedisConnectionFailureException Quick fix

Error phenomenon:

RedisConnectionFailureException: Unable to connect to Redis 

Solution:

Check whether the Redis service is started:

redis-cli ping  # Return to PONG to indicate normal

Confirm the Redis connection information in the configuration file:

spring:  
  redis:  
    host: localhost  
    port: 6379  
    password: 123456

10. Version incompatible: Spring Boot and third-party libraries version hell

Pit prevention tips:

Use the dependency management provided by Spring Boot:

<dependencyManagement>  
    <dependencies>  
        <dependency>  
            <groupId></groupId>  
            <artifactId>spring-boot-dependencies</artifactId>  
            <version>3.1.0</version>  
            <type>pom</type>  
            <scope>import</scope>  
        </dependency>  
    </dependencies>  
</dependencyManagement>

11. Static resource loading failure: Deep reasons for Whitelabel Error Page

Error phenomenon:

Returns the Spring Boot default error page when accessing static resources (such as HTML, JS).

Cause analysis:

Static resources are not placed in the src/main/resources/static or public directory.

Custom interceptors such as Spring Security intercept static requests.

The welcome page is not configured (priority is lower than controller routing).

Solution:

Check whether the resource path complies with the specification:

src/main/resources/  
├── static/  
│   └──  
└── public/  
    └──  

If Spring Security is used, release static resources:

@Configuration  
public class SecurityConfig extends WebSecurityConfigurerAdapter {  
    @Override  
    protected void configure(HttpSecurity http) throws Exception {  
        ()  
            .antMatchers("/static/**", "/public/**").permitAll();  
    }  
}

Pit prevention tips:

Priority is given to using classpath:/static/ to store resources to avoid path confusion.

12. Profile configuration error: What to do if No active profile set?

Error phenomenon:

No active profile set, falling back to default profiles: default  

Cause analysis:

Profile was not activated with startup parameters, environment variables, or configuration files.

Application-{profile}.yml file naming error.

Solution:

Command line activation:

java -jar  --=prod

Environment variable activation:

export SPRING_PROFILES_ACTIVE=dev && java -jar

Hard coded configuration files (production environment is not recommended):

#   
spring:  
  profiles:  
    active: dev

Pit prevention tips:

Production environments prohibit hard-code active in configuration files, and external configurations (such as Kubernetes ConfigMap) are recommended.

13. AOP proxy problem: The pit of BeanNotOfRequiredTypeException

Error phenomenon:

BeanNotOfRequiredTypeException: Bean named 'userService' is expected to be of type '' but was actually of type 'jdk.proxy2.$Proxy123'  

Cause analysis:

The proxy classes generated by JDK dynamic proxy are incompatible with the original class types.

The target class does not implement the interface, but the JDK proxy is forced.

Solution:

Force the use of CGLIB proxy (modify configuration):

#   
spring:  
  aop:  
    proxy-target-class: true

The target class implements an empty interface (compatible with JDK proxy).

Code example:

public interface UserServiceInterface {}  
 
@Service  
public class UserService implements UserServiceInterface { ... }

14. Log conflict: SLF4J binds multiple implementations

Error phenomenon:

SLF4J: Class path contains multiple SLF4J bindings.  
SLF4J: Found binding in [jar:file:/.../!/org/slf4j/impl/]  
SLF4J: Found binding in [jar:file:/.../!/org/slf4j/impl/]  

Solution:

Maven excludes conflict dependencies:

<dependency>  
    <groupId></groupId>  
    <artifactId>spring-boot-starter-web</artifactId>  
    <exclusions>  
        <exclusion>  
            <groupId></groupId>  
            <artifactId>spring-boot-starter-logging</artifactId>  
        </exclusion>  
    </exclusions>  
</dependency>  
<dependency>  
    <groupId></groupId>  
    <artifactId>spring-boot-starter-log4j2</artifactId>  
</dependency>

Gradle excludes conflicts:

 {  
    exclude group: '', module: 'spring-boot-starter-logging'  
}

15. Memory overflow: Emergency handling

Error phenomenon:

: Java heap space  
// or: Metaspace

Emergency handling:

Temporary capacity expansion: Adjust JVM parameters (examples are heap memory and metaspace):

java -Xmx1024m -Xms512m -XX:MaxMetaspaceSize=256m -jar

Memory analysis:

Generate a heap dump using jmap:

jmap -dump:format=b,file= <PID>

Use VisualVM or Eclipse MAT to analyze memory leaks.

Pit prevention tips:

Regularly monitor production environment memory usage (such as Prometheus + Grafana).

16. Third-party library compatibility: The secret of Jackson serialization error

Error phenomenon:

: No serializer found for class  

Solution:

Add @Getter/@Setter (Lombok) to the entity class or implement the getter method manually.

Ignore unknown fields (global configuration):

spring:  
  jackson:  
    default-property-inclusion: non_null  
    deserialization:  
      FAIL_ON_UNKNOWN_PROPERTIES: false

If you use the record class, add the @JsonAutoDetect annotation:

@JsonAutoDetect(fieldVisibility = )  
public record User(String name) {}

17. Security configuration error: Common interception issues in Spring Security

Error phenomenon:

The request is intercepted and returns 403 Forbidden or jump to the login page.

Solution:

Release public resource path:

@Override  
protected void configure(HttpSecurity http) throws Exception {  
    ()  
        .antMatchers("/", "/login", "/css/**").permitAll()  
        .anyRequest().authenticated()  
        .and()  
        .formLogin();  
}

Disable CSRF (API projects only):

().disable();

Pit prevention tips:

CSRF protection must be enabled in the production environment and can be disabled only for stateless API services.

18. Asynchronous thread pool configuration: troubleshooting of @Async annotation failure

Error phenomenon:

@Async method is executed synchronously, and the asynchronous thread is not triggered.

Solution:

Enable asynchronous support (add comments to the main class):

@SpringBootApplication  
@EnableAsync // Key notespublic class Application { ... }

Custom thread pool (avoid default thread pool blocking):

@Configuration  
public class AsyncConfig {  
    @Bean("taskExecutor")  
    public Executor taskExecutor() {  
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();  
        (10);  
        (20);  
        (200);  
        ();  
        return executor;  
    }  
}

Call example:

@Async("taskExecutor")  
public void asyncProcess() { ... }

19. Hot deployment failed: Hidden configuration that does not take effect in DevTools

Error phenomenon:

The code is not automatically restarted after modifying it.

Solution:

IDE configuration:

  • IntelliJ: Settings → Build → Compiler → Build project automatically
  • Eclipse: Enable Project → Build Automatically

Add DevTools dependencies:

<dependency>  
    <groupId></groupId>  
    <artifactId>spring-boot-devtools</artifactId>  
    <scope>runtime</scope>  
    <optional>true</optional>  
</dependency>

Exclude static resource restart (improve speed):

spring:  
  devtools:  
    restart:  
      exclude: static/**,public/**

20. Metaphysical error: How to save yourself when the log is blank?

Error phenomenon:

There is no log output after the application is started.

Solution:

Check or for configuration errors.

Force to specify the log level:

logging:  
  level:  
    root: INFO

Add default log dependencies:

<dependency>  
    <groupId></groupId>  
    <artifactId>spring-boot-starter-logging</artifactId>  
</dependency>

Ultimate Pit Protection Guide

Atomization verification: Test immediately after each configuration is modified to avoid the overlay of multiple changes that cause complexity of the problem.

Log level control: Adjust the log level to DEBUG or TRACE when encountering problems:

logging:  
  level:  
    root: DEBUG  
    : TRACE

Minimize reproduction: Extract core code to independent demo projects and eliminate irrelevant dependency interference.

The above is the detailed content of the ultimate guide to troubleshooting and solving 11 high-frequency problems caused by SpringBoot startup errors. For more information about SpringBoot startup errors, please pay attention to my other related articles!