Solutions for Spring Boot projects failing to start when integrating Elasticsearch

by

1. Bean definition conflict

1. MyBatis and Elasticsearch Repository scan path conflict

Error message :

org.springframework.context.annotation.ConflictingBeanDefinitionException: 
Annotation-specified bean name 'articlesRepository' for bean class [com.dragon.springboot3vue3.mapper.ArticlesRepository] conflicts with existing, non-compatible bean definition of same name and class [org.springframework.data.elasticsearch.repository.support.ElasticsearchRepositoryFactoryBean]

reason :

  • @MapperScan The MyBatis annotation and  @EnableElasticsearchRepositories the Spring Data annotation scanned the same package path.

Solution :

  1. Split package path (recommended):
@SpringBootApplication
@MapperScan("com.example.mapper") // MyBatis Mapper
@EnableElasticsearchRepositories("com.example.es.repository") // ES Repository
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}
  1. Alternatively, remove the annotation to allow Spring Boot to scan automatically:
@SpringBootApplication
// Annotate the following two lines
// @MapperScan("com.example.mapper")
// @EnableElasticsearchRepositories("com.example.es.repository")
public class Application {
    // ...
}

II. Dependency Configuration Issues

1. Missing or incompatible dependencies.

Error message :

NoSuchBeanDefinitionException: No bean named 'elasticsearchTemplate' available

reason :

  • Spring Data Elasticsearch dependency not properly imported
  • Dependency version incompatible with Spring Boot

Solution :

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-elasticsearch</artifactId>
    <!-- Exclude Netty dependencies that may cause conflicts -->
    <exclusions>
        <exclusion>
            <groupId>io.netty</groupId>
            <artifactId>netty-all</artifactId>
        </exclusion>
    </exclusions>
</dependency>

III. Elasticsearch service connection issues

1. The Elasticsearch service is not started or the address is misconfigured.

Error message :

org.elasticsearch.client.ResponseException: method [GET], host [http://localhost:9200], URI [/_cluster/health/], status line [HTTP/1.1 404 Not Found]
Not Found

reason :

  • The Elasticsearch service is not started.
  • The configured address does not match the actual Elasticsearch address (e.g., it is configured as localhost but is actually on another host).

Solution :

spring:
  elasticsearch:
    rest:
      uris: http://your-elasticsearch-server:9200 # Replace with your url

IV. Version compatibility issues

1. Spring Boot is incompatible with Elasticsearch versions.

Error message :

Factory method 'highLevelClient' threw exception
org.springframework.beans.BeanInstantiationException: Failed to instantiate [org.elasticsearch.client.RestHighLevelClient]: 
Factory method 'highLevelClient' threw exception

reason :

  • The Spring Boot version is incompatible with the Elasticsearch client version.
  • Dependency conflicts (e.g., Spring Boot 2.0.3 depends on Elasticsearch 5.6.10 by default, but the project uses version 7.5.2).

Solution :

  1. Ensure Spring Boot is compatible with Elasticsearch versions.
  2. Explicitly exclude the default version and specify the correct version:
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-elasticsearch</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.elasticsearch.client</groupId>
            <artifactId>elasticsearch-rest-high-level-client</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>org.elasticsearch.client</groupId>
    <artifactId>elasticsearch-rest-high-level-client</artifactId>
    <version>7.5.2</version>
</dependency>

V. Elasticsearch Health Check Issues

1. Actuator health check failed.

Error message :

ElasticsearchHealthCheck failed

reason :

  • Spring Boot Actuator is used by default http://localhost:9200 for health checks.
  • Elasticsearch is deployed on a non-localhost address.

Solution :

  1. Disable Elasticsearch health checks (recommended):
management:
  health:
    elasticsearch:
      enabled: false
  1. Configure the correct Elasticsearch address:
spring:
  elasticsearch:
    rest:
      uris: http://your-elasticsearch-server:9200

VI. Conflicts between Netty and Spring Data Elasticsearch

1. Conflicts between Netty and Spring Data Elasticsearch

Error message :

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

reason :

  • Spring Data Elasticsearch conflicts with Webflux components (based on Netty).

Solution :

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

VII. Incorrect configuration file format

1. Incorrect configuration file format (YAML indentation issue)

Error message :

Caused by: 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.

reason :

  • Incorrect indentation or spelling in the YAML file

Solution :
Ensure correct configuration:

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

VIII. Other Common Issues

1. Field mapping conflict

Error message :

ElasticsearchStatusException: MapperParsingException[failed to parse]

reason :

  • The entity class field type is inconsistent with the existing field type in the Elasticsearch index.

Solution :

  1. Restart the application after deleting (or rebuilding) the old index.
  2. Or migrate data via the _reindex API

2. The query result is empty.

Error message :

No documents found for query

reason :

  • Tokenizer mismatch (e.g., IK tokenizer not used for Chinese characters)
  • Query condition error

Solution :

  1. Check the index mapping using Kibana: GET your_index/_mapping
  2. Confirm word segmentation configuration
  3. Print the generated DSL query statement to verify the conditions

Summarize

  1. Ensure the Elasticsearch service is running : Use curl http://localhost:9200 verification
  2. Configure the connection address correctly : Set it in application.yml spring.elasticsearch.rest.uris
  3. Handling dependency conflicts : Exclude Netty dependencies and ensure version compatibility.
  4. Separate package paths : Avoid MyBatis and Elasticsearch Repository scan conflicts
  5. Turn off health checks : If not needed, set …management.health.elasticsearch.enabled=false
  6. Handling Netty conflicts : Add EsConfig a configuration class
  7. Check the configuration format : Ensure that the YAML indentation is correct and there are no spelling errors.