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.

Why is this an issue?

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.

What is the potential impact?

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.

How to fix it in Spring

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.

Code examples

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.

Noncompliant code example

@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
}

Compliant solution

@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.

Noncompliant code example

@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
}

Compliant solution

@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
}

Resources

Documentation