SpringBoot项目整合Elasticsearch启动失败的常见错误总结(2)

❃博主首页 ： 「程序员1970」 ，同名公众号「程序员1970」
☠博主专栏 ： <mysql高手> <elasticsearch高手> <源码解读> <java核心> <面试攻关>

---

文章目录

• • [九、Spring Boot 3与Jakarta EE命名空间问题](#九、Spring Boot 3与Jakarta EE命名空间问题)
  • • [1. 旧版客户端与Spring Boot 3不兼容](#1. 旧版客户端与Spring Boot 3不兼容)
  • 十、Elasticsearch连接超时问题
  • • [1. 启动时ES服务未完全就绪](#1. 启动时ES服务未完全就绪)
  • 十一、中文分词配置问题
  • • [1. 未安装IK分词器导致启动失败](#1. 未安装IK分词器导致启动失败)
  • 十二、索引映射配置错误
  • • [1. 实体类字段类型与索引映射不匹配](#1. 实体类字段类型与索引映射不匹配)
  • 十三、版本兼容性问题
  • • [1. Spring Boot与Spring Data Elasticsearch版本不匹配](#1. Spring Boot与Spring Data Elasticsearch版本不匹配)
  • 十四、依赖冲突问题
  • • [1. 与Netty依赖冲突](#1. 与Netty依赖冲突)
  • 十五、配置文件错误
  • • [1. 未正确配置Elasticsearch连接](#1. 未正确配置Elasticsearch连接)
  • 十六、索引自动创建问题
  • • [1. 索引自动创建导致映射冲突](#1. 索引自动创建导致映射冲突)

SpringBoot项目整合Elasticsearch启动失败的常见错误总结(1)

九、Spring Boot 3与Jakarta EE命名空间问题

1. 旧版客户端与Spring Boot 3不兼容

报错内容：

Caused by: java.lang.NoClassDefFoundError: javax/xml/bind/Unmarshaller

原因：

• Spring Boot 3使用Jakarta EE命名空间（jakarta.*包），不再支持Java EE（javax.*包）
• 依赖了旧版Elasticsearch客户端（基于Java EE）

解决方案：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-elasticsearch</artifactId>
</dependency>
<properties>
    <elasticsearch.version>8.9.0</elasticsearch.version>
</properties>

十、Elasticsearch连接超时问题

1. 启动时ES服务未完全就绪

报错内容：

org.elasticsearch.client.ResponseException: method [GET], host [http://localhost:9200], URI [/_cluster/health/], status line [HTTP/1.1 503 Service Unavailable]

原因：

• Elasticsearch服务启动较慢，应用启动时ES服务未完全就绪
• 默认连接超时时间过短

解决方案：

spring:
  elasticsearch:
    rest:
      uris: http://localhost:9200
      connection-timeout: 10000 # 10秒
      socket-timeout: 30000 # 30秒

十一、中文分词配置问题

1. 未安装IK分词器导致启动失败

报错内容：

org.elasticsearch.index.mapper.MapperParsingException: failed to parse [content]

原因：

• 未安装IK分词器插件
• 未在实体类中正确配置分词器

解决方案：

1. 安装IK分词器插件：

   bin/elasticsearch-plugin install https://github.com/medcl/elasticsearch-analysis-ik/releases/download/v8.9.0/elasticsearch-analysis-ik-8.9.0.zip

2. 在实体类中正确配置：

   @Field(type = FieldType.Text, analyzer = "ik_max_word", searchAnalyzer = "ik_smart")
   private String content;

十二、索引映射配置错误

1. 实体类字段类型与索引映射不匹配

报错内容：

org.elasticsearch.index.mapper.MapperParsingException: failed to parse [dateField]

原因：

• 实体类中日期字段类型与ES索引映射不匹配
• 未正确配置@Field注解

解决方案：

// 正确配置日期字段
@Field(type = FieldType.Date, format = DateFormat.date_hour_minute_second)
private LocalDateTime dateField;

十三、版本兼容性问题

1. Spring Boot与Spring Data Elasticsearch版本不匹配

报错内容：

Caused by: java.lang.NoSuchMethodError: 
org.springframework.data.elasticsearch.core.ElasticsearchRestClient.getRestHighLevelClient()Lorg/elasticsearch/client/RestHighLevelClient;

原因：

• Spring Boot版本与Spring Data Elasticsearch版本不兼容

Spring Boot与Spring Data Elasticsearch版本映射关系：

Spring Boot版本	Spring Data Elasticsearch版本	支持的Elasticsearch服务器版本
2.7.x	4.4.x	7.17.x
3.0.x ~ 3.1.x	5.1.x	8.7.x
3.2.x	5.2.x	8.9.x
3.3+	5.3+	8.10+

解决方案：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-elasticsearch</artifactId>
</dependency>
<properties>
    <elasticsearch.version>8.9.0</elasticsearch.version>
</properties>

十四、依赖冲突问题

1. 与Netty依赖冲突

报错内容：

availableProcessors is already set to [8], rejecting [8]

原因：

• Spring Data Elasticsearch与Webflux组件（基于Netty）发生冲突

解决方案：

@Configuration
public class EsConfig {
    @PostConstruct
    void init() {
        System.setProperty("es.set.netty.runtime.available.processors", "false");
    }
}

十五、配置文件错误

1. 未正确配置Elasticsearch连接

报错内容：

org.springframework.beans.factory.BeanCreationException: 
Error creating bean with name 'elasticsearchRestClient' defined in class path resource 
[org/springframework/boot/autoconfigure/data/elasticsearch/ElasticsearchRestClientAutoConfiguration.class]: 
Cannot create a ElasticsearchRestClient for the given configuration.

原因：

• 配置了错误的连接属性（如使用spring.data.elasticsearch.cluster-nodes而不是spring.elasticsearch.rest.uris）

正确配置：

spring:
  elasticsearch:
    rest:
      uris: http://localhost:9200

十六、索引自动创建问题

1. 索引自动创建导致映射冲突

报错内容：

ElasticsearchStatusException: MapperParsingException[failed to parse]

原因：

• Spring Data Elasticsearch在第一次操作时自动创建索引，但映射不符合预期

解决方案：

1. 在应用启动时手动创建索引：

@Component
public class IndexInitializer {
    @EventListener(ApplicationReadyEvent.class)
    public void initIndex() {
        ElasticsearchRestTemplate template = ...; // 注入
        if (!template.indexExists(User.class)) {
            template.createIndex(User.class);
            template.putMapping(User.class);
        }
    }
}

2. 或提前在Kibana中创建索引模板

---

关注公众号获取更多技术干货 !