@Autowired Explained: By-Type Resolution, @Qualifier, @Primary, ObjectProvider and List Injection

Versions. Spring Boot 4.1.1 and Spring Framework 7.0.9 (both poms were published to Maven Central on 20 August 2026), on Java 25 (LTS, Temurin 25.0.4.1). The scenarios run on a plain Spring ApplicationContext, so only the container’s own rules are in play. If you have not read it, the previous article on constructor, setter and field injection explains how the handed-over bean reaches your class; this one is about which bean gets handed over.

@Autowired asks one question first: which beans have this type?

/** Asks for a PaymentGateway and says nothing more. */
public class CheckoutPlain {

    private final PaymentGateway gateway;

    public CheckoutPlain(PaymentGateway gateway) {
        this.gateway = gateway;
    }

    public String gatewayClass() {
        return gateway.getClass().getSimpleName();
    }
}

top exception : org.springframework.beans.factory.UnsatisfiedDependencyException
top message   : Error creating bean with name 'checkoutPlain': Unsatisfied dependency expressed through constructor parameter 0: No qualifying bean of type 'com.ankurm.coredi.injection.PaymentGateway' available: expected at least 1 bean which qualifies as autowire candidate. Dependency annotations: {}

root cause    : org.springframework.beans.factory.NoSuchBeanDefinitionException
root message  : No qualifying bean of type 'com.ankurm.coredi.injection.PaymentGateway' available: expected at least 1 bean which qualifies as autowire candidate. Dependency annotations: {}

The fingerprint of the zero-candidate case. expected at least 1 bean which qualifies as autowire candidate at the bottom, wrapped in an UnsatisfiedDependencyException whose message names the consumer (checkoutPlain) and the exact parameter (constructor parameter 0). The last part, Dependency annotations: {}, lists the annotations Spring saw on the injection point; empty means there was no @Qualifier or anything else narrowing the request. Read that line first when you are unsure whether a qualifier is being applied.

Going deeper

• Reference: Spring Framework – Using @Autowired
• Source: CandidateResolutionTest.java is the test that writes every transcript in this article
• Previous article: Dependency Injection in Spring Boot 4: Constructor vs Setter vs Field for how the bean arrives once it has been chosen

Two candidates and no hint: the exact error, and what it is telling you

            var outcome = Ctx.tryStart(StripeGateway.class, PaypalGateway.class, CheckoutPlain.class);

started: false
top exception : org.springframework.beans.factory.UnsatisfiedDependencyException
top message   : Error creating bean with name 'checkoutPlain': Unsatisfied dependency expressed through constructor parameter 0: No qualifying bean of type 'com.ankurm.coredi.injection.PaymentGateway' available: expected single matching bean but found 2: stripeGateway,paypalGateway

root cause    : org.springframework.beans.factory.NoUniqueBeanDefinitionException
root message  : No qualifying bean of type 'com.ankurm.coredi.injection.PaymentGateway' available: expected single matching bean but found 2: stripeGateway,paypalGateway

The fingerprint of the ambiguous case. expected single matching bean but found 2: stripeGateway,paypalGateway. The two names at the end are the bean names Spring will accept in a @Qualifier, so the message is also the list of valid answers. Stripe was registered first and it did not win: registration order is not a tie-breaker, so “the first one” is never what you get.

Going deeper

• Reference: Fine-tuning annotation-based autowiring with @Primary or @Fallback
• Source: PaypalGateway.java

Five hints, and the order Spring tries them

public class CheckoutQualified {

    private final PaymentGateway gateway;

    public CheckoutQualified(@Qualifier("paypalGateway") PaymentGateway gateway) {
        this.gateway = gateway;
    }

    public String gatewayClass() {
        return gateway.getClass().getSimpleName();
    }
}

@Primary
public class PrimaryStripeGateway extends StripeGateway {
}

@Priority(2)
public class PriorityTwoGateway extends PaypalGateway {
}

beans registered / injection point                         winner
---------------------------------------------------------- --------------------
@Primary Stripe + Paypal; CheckoutPlain                    PrimaryStripeGateway
@Primary Stripe + Paypal; @Qualifier("paypalGateway")      PaypalGateway
@Priority(1) Stripe + @Priority(2) Paypal; CheckoutPlain   PriorityOneGateway
@Priority(1) + Paypal(no priority); param named paypalGateway PaypalGateway
Stripe + Paypal (plain); param named paypalGateway         PaypalGateway
Stripe (plain) + @Fallback Paypal; CheckoutPlain           StripeGateway
@Fast custom qualifier, FastGateway + Paypal; @Fast param  FastGateway

The surprise is row 4. One bean carries @Priority(1), the other has no annotation but its name matches the parameter name, and the unannotated bean wins. If you assume “annotations beat names”, this is the row that breaks the assumption. It is measured on Spring Framework 7.0.9 and it agrees with the order of the calls in the bytecode below; do not build a design around a subtle precedence between two hints. If you need a specific bean, say so with @Qualifier.

# jar: spring-beans-7.0.9.jar

  protected java.lang.String determineAutowireCandidate(java.util.Map<java.lang.String, java.lang.Object>, org.springframework.beans.factory.config.DependencyDescriptor);
invokevirtual #1076               // Method org/springframework/beans/factory/config/DependencyDescriptor.getDependencyType:()Ljava/lang/Class;
invokevirtual #1039               // Method determinePrimaryCandidate:(Ljava/util/Map;Ljava/lang/Class;)Ljava/lang/String;
invokevirtual #1169               // Method org/springframework/beans/factory/config/DependencyDescriptor.getDependencyName:()Ljava/lang/String;
invokeinterface #970,  1          // InterfaceMethod java/util/Map.keySet:()Ljava/util/Set;
invokeinterface #397,  1          // InterfaceMethod java/util/Set.iterator:()Ljava/util/Iterator;
invokeinterface #304,  1          // InterfaceMethod java/util/Iterator.hasNext:()Z
invokeinterface #309,  1          // InterfaceMethod java/util/Iterator.next:()Ljava/lang/Object;
invokevirtual #1393               // Method matchesBeanName:(Ljava/lang/String;Ljava/lang/String;)Z
invokevirtual #150                // Method getAutowireCandidateResolver:()Lorg/springframework/beans/factory/support/AutowireCandidateResolver;
invokeinterface #1172,  2         // InterfaceMethod org/springframework/beans/factory/support/AutowireCandidateResolver.getSuggestedName:(Lorg/springframework/beans/factory/config/DependencyDescriptor;)Ljava/lang/String;
invokeinterface #970,  1          // InterfaceMethod java/util/Map.keySet:()Ljava/util/Set;
invokeinterface #397,  1          // InterfaceMethod java/util/Set.iterator:()Ljava/util/Iterator;
invokeinterface #304,  1          // InterfaceMethod java/util/Iterator.hasNext:()Z
invokeinterface #309,  1          // InterfaceMethod java/util/Iterator.next:()Ljava/lang/Object;
invokevirtual #1393               // Method matchesBeanName:(Ljava/lang/String;Ljava/lang/String;)Z
invokevirtual #1043               // Method determineHighestPriorityCandidate:(Ljava/util/Map;Ljava/lang/Class;)Ljava/lang/String;
invokevirtual #1046               // Method determineDefaultCandidate:(Ljava/util/Map;)Ljava/lang/String;
invokeinterface #1230,  1         // InterfaceMethod java/util/Map.entrySet:()Ljava/util/Set;
invokeinterface #397,  1          // InterfaceMethod java/util/Set.iterator:()Ljava/util/Iterator;
invokeinterface #304,  1          // InterfaceMethod java/util/Iterator.hasNext:()Z
invokeinterface #309,  1          // InterfaceMethod java/util/Iterator.next:()Ljava/lang/Object;
invokeinterface #1235,  1         // InterfaceMethod java/util/Map$Entry.getKey:()Ljava/lang/Object;
invokeinterface #1238,  1         // InterfaceMethod java/util/Map$Entry.getValue:()Ljava/lang/Object;
invokeinterface #1399,  2         // InterfaceMethod java/util/Map.containsValue:(Ljava/lang/Object;)Z

/** A custom qualifier: a meta-annotation over {@code @Qualifier}, so call sites do not repeat a string. */
@Target({ElementType.TYPE, ElementType.PARAMETER, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
@Qualifier
public @interface Fast {
}

public class CheckoutFast {

    private final PaymentGateway gateway;

    public CheckoutFast(@Fast PaymentGateway gateway) {
        this.gateway = gateway;
    }

    public String gatewayClass() {
        return gateway.getClass().getSimpleName();
    }
}

@Resource             : paypalGateway field -> PaypalGateway, whateverIWantToCallIt field -> StripeGateway

Going deeper

• Reference: Fine-tuning annotation-based autowiring with qualifiers
• Reference: Using @Resource
• Source: FastGateway.java and PriorityOneGateway.java

Matching by parameter name only works if the compiler kept the names

/** The parameter name is the only hint: it matches the bean name {@code paypalGateway}. */
public class CheckoutNamed {

    private final PaymentGateway paypalGateway;

    public CheckoutNamed(PaymentGateway paypalGateway) {
        this.paypalGateway = paypalGateway;
    }

    public String gatewayClass() {
        return paypalGateway.getClass().getSimpleName();
    }
}

javac -parameters  : started, picked PaypalGateway
javac (no flag)    : FAILED NoUniqueBeanDefinitionException
    No qualifying bean of type 'com.ankurm.coredi.injection.PaymentGateway' available: expected single matching bean but found 2: stripeGateway,paypalGateway

The fingerprint. expected single matching bean but found 2 for a class that looks as if it names its bean. If a parameter or field name is the only thing selecting a bean, and a build that used to work starts failing after a build-tool or compiler-option change, check the -parameters flag first.

111-          <artifactId>maven-compiler-plugin</artifactId>
112-          <configuration>
113:            <parameters>true</parameters>
114-          </configuration>
115-        </plugin>

Going deeper

• Source: CheckoutNamed.java and the test method parameterNameFallbackNeedsTheParametersFlag in CandidateResolutionTest.java
• Related on this site: Spring Framework 6 to 7 Migration Guide for other things that changed with the 7.0 line

When the bean may not exist: Optional, @Nullable and ObjectProvider

    public static class WithProvider {
        public final ObjectProvider<Notifier> provider;

        public WithProvider(ObjectProvider<Notifier> provider) {
            this.provider = provider;
        }
    }

--- zero Notifier beans ---
plain constructor param          : FAILED NoSuchBeanDefinitionException
Optional<Notifier>               : isPresent=false
@Nullable Notifier               : value=null
ObjectProvider.getIfAvailable()  : null
ObjectProvider.getIfUnique()     : null
ObjectProvider.getObject()       : NoSuchBeanDefinitionException: No qualifying bean of type 'com.ankurm.coredi.injection.Notifier' available: expected at least 1 bean which qualifies as autowire candidate. Dependency annotations: {}
@Autowired(required=false) setter: value=null

--- two Notifier beans (Sms, Email), no @Primary ---
ObjectProvider.getIfAvailable()  : NoUniqueBeanDefinitionException: No qualifying bean of type 'com.ankurm.coredi.injection.Notifier' available: expected single matching bean but found 2: emailNotifier,smsNotifier
ObjectProvider.getIfUnique()     : null
ObjectProvider.stream() classes  : [EmailNotifier, SmsNotifier]
ObjectProvider.orderedStream()   : [SmsNotifier, EmailNotifier]
Optional<Notifier> with two beans: FAILED NoUniqueBeanDefinitionException
  No qualifying bean of type 'com.ankurm.coredi.injection.Notifier' available: expected single matching bean but found 2: emailNotifier,smsNotifier

Optional is not a tie-breaker. Optional<Notifier> reads as “one or nothing”, but two beans is neither, and the injection fails with the same NoUniqueBeanDefinitionException as a plain parameter. ObjectProvider.getIfAvailable() throws the same exception; getIfUnique() is the method that returns null for “not exactly one”. Choose the method by what you want when the count is not one.

Going deeper

• Reference: Spring Framework – Using @Autowired (the sections on required, Optional, @Nullable and ObjectProvider)
• Source: EmailNotifier.java and SmsNotifier.java

Injecting every bean of a type: List, Map and Set

/** Receives every Notifier three ways: as a List, a Map keyed by bean name, and a Set. */
public class Broadcaster {

    public final List<Notifier> asList;
    public final Map<String, Notifier> asMap;
    public final Set<Notifier> asSet;

    public Broadcaster(List<Notifier> asList, Map<String, Notifier> asMap, Set<Notifier> asSet) {
        this.asList = asList;
        this.asMap = asMap;
        this.asSet = asSet;
    }
}

List<Notifier> order   : [SmsNotifier, EmailNotifier, PushNotifier]
Map<String,Notifier>   : [pushNotifier, emailNotifier, smsNotifier]
Set<Notifier> size     : 3

/** The generic type argument is part of the injection point: only Handler<String> beans arrive. */
public class GenericConsumer {

    public final List<Handler<String>> stringHandlers;
    public final Handler<Integer> integerHandler;

    public GenericConsumer(List<Handler<String>> stringHandlers, Handler<Integer> integerHandler) {
        this.stringHandlers = stringHandlers;
        this.integerHandler = integerHandler;
    }
}

List<Handler<String>>  : [StringHandler]
Handler<Integer>       : IntegerHandler

Going deeper

• Reference: Spring Framework – Using @Autowired (injecting collections and maps)
• Source: PushNotifier.java (the bean with no @Order)

The empty-collection trap: constructors say yes, fields and setters say no

    public static class Plain {
        public Plain(List<Plugin> plugins) {
        }
    }

    public static class FieldInjected {
        @Autowired
        public List<Plugin> plugins;
    }

--- required List<Plugin>, zero Plugin beans ---
single constructor param      : started (empty list injected)
@Autowired ctor + no-arg ctor  : started (empty list injected)
FieldInjected              : FAILED NoSuchBeanDefinitionException
    No qualifying bean of type 'java.util.List<com.ankurm.coredi.resolution.Plugin>' available: expected at least 1 bean which qualifies as autowire candidate. Dependency annotations: {@org.springframework.beans.factory.annotation.Autowired(required=true)}
SetterInjected             : FAILED NoSuchBeanDefinitionException
    No qualifying bean of type 'java.util.List<com.ankurm.coredi.resolution.Plugin>' available: expected at least 1 bean which qualifies as autowire candidate. Dependency annotations: {}

--- ways to make an absent collection legal ---
Optional<List<Plugin>>          : isPresent=false
@Nullable List<Plugin>          : value=null
ObjectProvider<Plugin> -> list  : []
@Autowired(required=false) list: []

The fingerprint. No qualifying bean of type 'java.util.List<com.ankurm.coredi.resolution.Plugin>' — a collection type inside the quotes — and, on the field variant, Dependency annotations: {@org.springframework.beans.factory.annotation.Autowired(required=true)} showing that required=true is the default. A refactor from a constructor to a field can turn “starts with no plug-ins” into “will not start”, and nothing in the diff looks like a behaviour change.

Going deeper

• Source: CandidateResolutionTest.java (emptyCollections)
• Reference: Spring Framework – Using @Autowired

So which hint, and when

Should you even care, on a small project? If every interface in your application has one implementation, none of this will ever fire, and you can leave it unread. It starts to matter the day a second implementation appears — often by adding a stub, a second provider or a library that registers its own bean — and the message at that point is a start-up failure, which is the cheapest place to learn it. Two points are opinion rather than measurement: prefer an explicit @Qualifier at the injection point over @Primary when a wrong choice would be costly, because it reads as a decision at the call site; and treat a growing pile of hints as a sign that the abstraction is doing two jobs.

Going deeper

• Previous: Dependency Injection in Spring Boot 4: Constructor vs Setter vs Field
• Next: Spring Bean Scopes and the Prototype-in-Singleton Trap (where ObjectProvider repairs a real bug) and Spring Bean Lifecycle in Boot 4
• Related on this site: @ConfigurationProperties vs @Value in Spring Boot 4

Further reading

• Companion repository for this article: asmhatre/spring-boot-demo, core-di module
• Other articles in this series: Constructor vs Setter vs Field injection, Spring Bean Scopes, Spring Bean Lifecycle
• Interview preparation: Top 50 Spring Boot 4 Interview Questions and Answers (2026)
• Official reference: Spring Framework – Using @Autowired
• Official reference: Spring Framework – Fine-tuning with qualifiers and @Primary and @Fallback
• Official reference: Spring Framework – Using @Resource