What is @Qualifier?

1. What is @Qualifier?

@Qualifier is an annotation in Spring used to resolve ambiguity when multiple beans of the same type exist in the Spring ApplicationContext.

It tells Spring:

"If you see multiple candidates, pick this exact bean for injection."

2. Why we need it

In Spring Boot, when you inject by type (@Autowired), Spring tries to find exactly one matching bean.


If two or more beans match the same type, Spring throws:

NoUniqueBeanDefinitionException:
No qualifying bean of type 'X' available: expected single matching bean but found 2: bean1, bean2

@Qualifier removes the guesswork and tells Spring exactly which bean to inject.

3. How it works

Example without @Qualifier (will fail)

public interface PaymentService {
    void pay();
}

@Service
public class CreditCardPaymentService implements PaymentService {
    public void pay() { System.out.println("Paid by Credit Card"); }
}

@Service
public class PaypalPaymentService implements PaymentService {
    public void pay() { System.out.println("Paid by PayPal"); }
}

@RestController
public class OrderController {
    @Autowired
    private PaymentService paymentService; // ❌ Ambiguity
}

When OrderController is created, Spring finds:

  • creditCardPaymentService
  • paypalPaymentService
    Both match PaymentService → ambiguity error.

Example with @Qualifier (will work)

@RestController
public class OrderController {

    @Autowired
    @Qualifier("paypalPaymentService")  // Bean name
    private PaymentService paymentService;

    @GetMapping("/order")
    public String placeOrder() {
        paymentService.pay();
        return "Order placed!";
    }
}

Here:

  • paypalPaymentService is the bean name (by default, same as class name with first letter lowercase).
  • Spring now knows exactly which bean to inject.

4. Using @Qualifier with Constructor Injection

Constructor injection is often preferred in Spring Boot for immutability and testability.

@RestController
public class OrderController {

    private final PaymentService paymentService;

    public OrderController(@Qualifier("creditCardPaymentService") PaymentService paymentService) {
        this.paymentService = paymentService;
    }
}

5. Custom Qualifier Names

You can also define your own custom qualifier names instead of relying on the default bean name.

@Service
@Qualifier("fastPayment")
public class PaypalPaymentService implements PaymentService {
    public void pay() { System.out.println("Paid by PayPal"); }
}

@Service
@Qualifier("securePayment")
public class CreditCardPaymentService implements PaymentService {
    public void pay() { System.out.println("Paid by Credit Card"); }
}

@RestController
public class OrderController {

    @Autowired
    @Qualifier("fastPayment")
    private PaymentService paymentService;
}

6. Key Points to Remember

  • Default bean name = class name with lowercase first letter (unless specified via @Bean(name = "...") or @Component("name")).
  • @Qualifier must match the bean’s name or custom qualifier string.
  • You can combine @Qualifier with @Primary — @Qualifier always overrides @Primary.
  • Works with field injection, setter injection, and constructor injection.

✅ Summary
@Qualifier in Spring Boot is used to disambiguate when multiple beans of the same type exist. You specify the bean name or a custom qualifier so Spring knows exactly which bean to inject. It’s especially useful in layered architectures where you have multiple implementations of the same interface.


Back to blog

Leave a comment