SpringBoot项目启动失败的常见错误总结

一、项目识别与依赖问题

1. 项目不被IDE识别为Maven项目

报错内容：

没有启动的三角按钮
项目结构缺少 Maven Dependencies

原因：IDEA没有将其识别为一个Maven项目

2. 依赖未下载或下载失败

报错内容：

Could not resolve dependencies
pom.xml 文件出现红色下划线

原因：依赖没有下载到本地或者本地文件残缺

二、配置文件问题

1. 配置文件编码错误（YAML）

报错内容：

Caused by: org.yaml.snakeyaml.error.YAMLException: java.nio.charset.MalformedInputException: Input length = 2

原因：application.yml文件编码不是UTF-8

2. 配置文件格式错误

报错内容：

Failed to load application context
Caused by: org.springframework.beans.factory.BeanDefinitionStoreException: Invalid bean definition with name 'org.springframework.boot.autoconfigure.internalCachingMetadataReaderFactory' defined in null: Could not resolve placeholder 'spring.application.name' in value "${spring.application.name}"

原因：YAML文件缩进不正确或格式错误

三、环境配置问题

1. JDK版本不匹配

报错内容：

Error: A JNI error has o***urred, please check your installation and try again
Invalid maximum heap size: -Xmx512m
The specified size exceeds the maximum representable size.

原因：使用的JDK版本与Spring Boot版本不匹配

• Spring Boot 3.x默认要求JDK 17+
• 17以下版本不支持

2. 端口被占用

报错内容：

*************************** APPLICATION FAILED TO START ***************************
Description: The Tomcat connector configured to listen on port 8080 failed to start. The port may already be in use or the connector may be misconfigured.
Action: Verify the connector's configuration, identify and stop any process that's listening on port 8080, or configure this application to listen on another port.

原因：8080端口被其他进程占用

四、依赖与Bean注入问题

1. 依赖冲突

报错内容：

Exception in thread "main" java.lang.NoSuchMethodError: org.springframework.core.annotation.AnnotationUtils.isCandidateClass(Ljava/lang/Class;Ljava/lang/Class;)Z

原因：不同依赖之间存在版本冲突

2. Bean找不到

报错内容：

org.springframework.beans.factory.NoSuchBeanDefinitionException: No qualifying bean of type '***.example.demo.service.UserService' available: expected at least 1 bean which qualifies as autowire candidate.

原因：

• 未添加@***ponent、@Service等注解
• 扫描路径不正确

3. Mapper扫描问题

报错内容：

Field clustersDetailsAmqMapper in ***.ruoyi.clusters.service.impl.ClustersDetailsAmqServiceImpl required a bean of type '***.ruoyi.clusters.mapper.ClustersDetailsAmqMapper' that could not be found.

原因：启动类未配置正确的Mapper扫描路径

五、数据库连接问题

1. 数据源配置缺失

报错内容：

org.springframework.boot.autoconfigure.jdbc.DataSourceProperties$DataSourceBeanCreationException: Failed to configure a DataSource: 'url' attribute is not specified and no embedded datasource could be configured.

原因：数据库配置缺失（如spring.datasource.url等）

2. 数据库连接失败

报错内容：

Unable to connect to database

原因：

• 数据库服务未启动
• 数据库用户名或密码错误
• 数据库URL配置错误

六、启动类问题

1. 启动类配置错误

报错内容：

找不到主类

原因：

• 启动类未正确标注@SpringBootApplication注解
• IDE运行配置主类路径错误
• 项目结构不正确

七、其他常见问题

1. 中文乱码问题

报错内容：

java.lang.IllegalArgumentException: Invalid character found in the request target. The valid characters are defined in RFC 7230 and RFC 3986

原因：编码格式不一致

2. 依赖版本不匹配

报错内容：

The following dependencies have a problem:
- spring-boot-starter-web: 2.4.3
- spring-cloud-starter-eureka: 2.2.12

原因：Spring Boot与Eureka等依赖版本不匹配