This is an issue when Spring dependency injection’s mechanism cannot determine which component to inject because multiple components of the same type exist in the application’s dependency injection container without explicit disambiguation.
Spring resolves autowiring by type: when exactly one bean matches the required type, it gets injected without further input. If two or more beans
of the same type exist in the application context, Spring cannot decide which one to use and expects the ambiguity to be resolved explicitly, for
example with @Qualifier, by marking one bean @Primary, or by ensuring only one candidate is registered.
Spring will throw a NoUniqueBeanDefinitionException exception at runtime, indicating ambiguous dependency resolution during the
dependency injection framework’s initialization phase. This prevents the application from running and requires immediate attention to resolve the
configuration error.
The ambiguity can be resolved in several ways, for example with @Qualifier, @Primary, or by restricting which beans are
registered with @Conditional and its variants. The two most common options are shown below.
Option 1: select the bean with @Qualifier
Use the @Qualifier annotation at the injection point to explicitly specify which bean to inject. The qualifier value must match the
bean name (typically the method name for @Bean methods).
This approach is useful when different parts of your application need different beans of the same type. Each injection point can specify exactly which bean it requires.
@Configuration
public class DataSourceConfig {
@Bean
public DataSource primaryDataSource() {
return new HikariDataSource();
}
@Bean
public DataSource secondaryDataSource() {
return new HikariDataSource();
}
}
@Service
public class ReportService {
@Autowired
private DataSource dataSource; // Noncompliant; Spring cannot determine which DataSource bean to inject
}
@Configuration
public class DataSourceConfig {
@Bean
public DataSource primaryDataSource() {
return new HikariDataSource();
}
@Bean
public DataSource secondaryDataSource() {
return new HikariDataSource();
}
}
@Service
public class ReportService {
@Autowired
@Qualifier("primaryDataSource")
private DataSource dataSource; // Compliant; @Qualifier explicitly specifies that primaryDataSource needs to be used
}
Option 2: mark a default bean with @Primary
Use the @Primary annotation on one of the bean definitions to mark it as the default choice. When Spring encounters multiple beans of
the same type, it will automatically select the primary bean if no explicit qualifier is specified.
This approach is useful when you have a clear default bean that should be used in most cases, with alternative beans available for specific scenarios.
@Configuration
public class DataSourceConfig {
@Bean
public DataSource primaryDataSource() {
return new HikariDataSource();
}
@Bean
public DataSource secondaryDataSource() {
return new HikariDataSource();
}
}
@Service
public class ReportService {
@Autowired
private DataSource dataSource; // Noncompliant
}
@Configuration
public class DataSourceConfig {
@Bean
@Primary
public DataSource primaryDataSource() {
return new HikariDataSource();
}
@Bean
public DataSource secondaryDataSource() {
return new HikariDataSource();
}
}
@Service
public class ReportService {
@Autowired
private DataSource dataSource; // Compliant; will use default primaryDataSource
}