Deep Analysis and Solution for UnsatisfiedDependencyException in Spring Boot Applications

Problem Background and Exception Analysis

In Spring Boot application development, database configuration is one of the core components. Developers often need to customize database connection configurations to meet specific requirements. However, when manual configurations conflict with Spring Boot's auto-configuration mechanism, complex dependency injection exceptions occur. In the case discussed in this paper, the developer encountered a typical UnsatisfiedDependencyException, with the root cause lying in version conflicts of Hibernate-related dependencies.

Deep Analysis of Exception Stack Trace

From the exception stack trace, it's evident that the problem originates from the failure to create the entityManagerFactory bean. When Spring Boot's auto-configuration class HibernateJpaAutoConfiguration attempts to create jpaVendorAdapter, it encounters NoClassDefFoundError: org/hibernate/OptimisticLockException. This error suggests missing necessary Hibernate classes in the classpath, but the actual situation is more complex.

The critical exception chain is as follows:

org.springframework.beans.factory.UnsatisfiedDependencyException: Error creating bean with name 'entityManagerFactory'
→ Error creating bean with name 'entityManagerFactoryBuilder'
→ Error creating bean with name 'jpaVendorAdapter'
→ java.lang.NoClassDefFoundError: org/hibernate/OptimisticLockException
→ java.lang.ClassNotFoundException: org.hibernate.OptimisticLockException

This exception chain reveals the dependency resolution sequence during Spring container initialization. When Spring attempts to create HibernateJpaVendorAdapter, it needs to load the HibernateJpaDialect class, which references OptimisticLockException during initialization. If incompatible Hibernate versions exist in the classpath, class loading fails.

Analysis of Original Configuration Issues

Analyzing the original pom.xml configuration reveals several critical issues:

Hibernate Version Conflicts

The configuration declares multiple Hibernate dependencies with inconsistent versions:

<dependency>
    <groupId>org.hibernate</groupId>
    <artifactId>hibernate-entitymanager</artifactId>
    <version>3.6.7.Final</version>
</dependency>
<dependency>
    <groupId>org.hibernate</groupId>
    <artifactId>hibernate-core</artifactId>
    <version>3.3.2.GA</version>
</dependency>

According to Maven's dependency resolution rules, later-declared dependencies override earlier ones. This means Hibernate 3.3.2.GA is actually used, which is incompatible with Spring Boot 1.2.3.RELEASE. Spring Boot 1.2.x series typically requires Hibernate 4.x or higher.

Redundant Dependency Declarations

The configuration contains multiple redundant or outdated dependencies:

• hibernate-commons-annotations: Already included in hibernate-entitymanager
• hibernate-annotations: Legacy annotation support for Hibernate 3.x, replaced by modern versions
• Duplicate spring-boot-starter-data-jpa declarations

Improper Version Management

When using Spring Boot as the parent POM, most dependency versions should be managed by Spring Boot. Manually specifying versions overrides Spring Boot's version management, potentially causing compatibility issues.

Solutions and Configuration Refactoring

Based on problem analysis, the refactored pom.xml should follow these principles:

Dependency Simplification Principle

Remove all redundant and conflicting dependencies, letting Spring Boot manage versions:

<dependency>
    <groupId>org.hibernate</groupId>
    <artifactId>hibernate-entitymanager</artifactId>
</dependency>
<dependency>
    <groupId>org.hibernate</groupId>
    <artifactId>hibernate-validator</artifactId>
</dependency>

Remove explicit declarations of hibernate-core, hibernate-commons-annotations, and hibernate-annotations, as these dependencies will be automatically introduced with correct versions through hibernate-entitymanager.

Configuration Class Optimization Suggestions

Although the original problem mainly lies in dependency configuration, the database configuration class can also be further optimized. In Spring Boot, manual configuration of LocalSessionFactoryBean and HibernateTransactionManager is usually unnecessary because spring-boot-starter-data-jpa already provides auto-configuration.

If custom configuration is indeed needed, a more concise approach is recommended:

@Configuration
@EnableTransactionManagement
public class DatabaseConfig {
    
    @Bean
    @ConfigurationProperties(prefix = "spring.datasource")
    public DataSource dataSource() {
        return DataSourceBuilder.create().build();
    }
    
    @Bean
    public LocalContainerEntityManagerFactoryBean entityManagerFactory(
            DataSource dataSource, JpaVendorAdapter jpaVendorAdapter) {
        LocalContainerEntityManagerFactoryBean em = new LocalContainerEntityManagerFactoryBean();
        em.setDataSource(dataSource);
        em.setPackagesToScan("com.example.entities");
        em.setJpaVendorAdapter(jpaVendorAdapter);
        return em;
    }
}

Spring Boot Auto-configuration Mechanism

Understanding Spring Boot's auto-configuration mechanism is crucial for avoiding such problems. When an application starts, Spring Boot:

1. Scans dependencies in the classpath
2. Decides whether to enable specific auto-configurations based on conditional annotations (e.g., @ConditionalOnClass)
3. Creates and configures necessary beans

In the case discussed in this paper, conditions for HibernateJpaAutoConfiguration include:

• @ConditionalOnClass({ LocalContainerEntityManagerFactoryBean.class, JpaVendorAdapter.class })
• @ConditionalOnBean(DataSource.class)

When these conditions are met, Spring Boot attempts to create JPA-related beans. If incompatible Hibernate versions exist in the classpath, class loading fails.

Best Practice Recommendations

Based on this case, the following best practices are proposed:

Dependency Management

1. Prefer Spring Boot's dependency management, avoid manually specifying versions
2. Regularly check for dependency conflicts using mvn dependency:tree for analysis
3. Remove redundant and outdated dependency declarations

Configuration Strategy

1. Use Spring Boot's auto-configuration whenever possible, customize only when necessary
2. Use @ConfigurationProperties for externalized configuration
3. Maintain simplicity and single responsibility in configuration classes

Error Troubleshooting

1. Carefully read exception stack traces to understand causal relationships in exception chains
2. Check for version conflicts in the classpath
3. Use IDE dependency analysis tools to assist troubleshooting

Conclusion

UnsatisfiedDependencyException: Error creating bean with name 'entityManagerFactory' is a common configuration issue in Spring Boot applications. Through in-depth analysis of exception stack traces and dependency configurations, the root causes can be identified, typically involving version conflicts or improper configurations. The solutions provided in this paper not only address specific exception problems but, more importantly, establish correct dependency management and configuration practices. In the Spring Boot ecosystem, understanding the auto-configuration mechanism and following best practices are key to avoiding similar issues.

For developers, mastering dependency management tools (such as Maven or Gradle), understanding Spring Boot's auto-configuration principles, and possessing systematic problem-solving skills are essential foundations for building stable, maintainable Spring Boot applications.