Could Not Autowire in Spring? Fix It Fast

You add one annotation, hit run, and Spring refuses to start: Could not autowire. No qualifying bean of type com.acme.BillingService. The class exists. The annotation is right there. Yet the application context won't build, the pipeline is red, and the error dumps a stack trace that reads like a riddle. Every Spring developer meets this failure, usually right before a demo.

The instinct is to annotate harder — add @Qualifier, add @ComponentScan, mark everything @Primary — until startup passes. That scattergun approach works once and poisons the codebase: qualifiers that name beans which don't exist, scan roots that sweep up test doubles, primaries that silently pick the wrong implementation for months. Each guess adds a line that the next developer must decode.

This guide teaches you to read the nested exception like a diagnosis instead of a complaint. You'll learn the two failure families — zero candidates versus too many — and the exact fix for each: @Qualifier and @Primary for ambiguity, scan layout for missing beans, cycle-breaking for constructor loops. By the end you'll fix wiring errors in minutes with one deliberate change instead of five hopeful ones.

No Qualifying Bean vs Multiple Candidates: Read the Error First

Every Could not autowire failure belongs to one of two families, and the nested exception tells you which. No qualifying bean of type X means zero candidates: Spring scanned everything and found nothing assignable to X. No unique bean of type X means two or more candidates with no tiebreak: Spring found options and refuses to guess. The outer UnsatisfiedDependencyException just says which injection point failed; the inner Caused by carries the diagnosis. Read inside-out, deepest cause first.

Zero-candidate failures trace to registration or visibility. The class lacks a stereotype (@Component, @Service, @Repository, @Controller), the @Bean method sits in a configuration class that's never scanned, or a conditional like @ConditionalOnProperty evaluated false. Confirm by dumping the beans Spring knows: hit /actuator/beans in a running sibling environment or add a failing context test that prints applicationContext.getBeanDefinitionNames(). If your type is absent from that list, no annotation at the injection point can help — you must register the bean.

Multi-candidate failures trace to growth: a second implementation merged, a test configuration leaked into the main scan, or a library auto-configuration contributed a bean you didn't expect. The exception message helpfully lists every match by name — read them. Each listed name is a real bean from a real source, and your fix is choosing among them once, explicitly. Never let the message's length panic you into @Primary-everything; two named candidates need one decision, not three annotations.

// Injection point from the incident — constructor states its need
@Service
public class CheckoutService {
    private final BillingService billing;

    public CheckoutService(BillingService billing) {
        this.billing = billing;
    }
}
// Zero beans  -> NoSuchBeanDefinitionException: No qualifying bean
// Two beans   -> NoUniqueBeanDefinitionException: expected single bean
// Read the nested 'Caused by' — it names the type and the family.

Fixing Ambiguity with @Qualifier at the Injection Point

@Qualifier resolves ambiguity at a single injection point by naming the bean you want. It pairs with explicit bean names — @Service("stripeBilling") — so the choice reads clearly at both ends. Constructor parameters take @Qualifier directly, which keeps the selection next to the dependency it governs. When checkout needs Stripe and refunds need PayPal, each constructor states its own answer and neither cares about the other.

Name beans deliberately or Spring names them for you with the decapitalized class name (stripeBillingService). Explicit names survive refactors of class names and read better in error messages. A useful convention: name by provider or role — stripeBilling, paypalBilling — not by layer. When the exception lists candidates, those names should already tell a reviewer which one each caller wants.

Scope @Qualifier to genuine per-caller choices. If every injection point names the same bean, that's not selection — that's a missing default, and @Primary expresses it in one place instead of ten. Qualifiers scattered identically across a codebase rot fast: rename the bean and you hunt ten files. One qualifier per genuinely different choice; a primary for the common case. Reviewers should be able to ask of each qualifier, why is this caller special, and get a real answer.

// Name the implementation once, choose it at each injection point
@Service("stripeBilling")
public class StripeBillingService implements BillingService { }

@Service("paypalBilling")
public class PaypalBillingService implements BillingService { }

@Service
public class CheckoutService {
    private final BillingService billing;

    public CheckoutService(@Qualifier("stripeBilling") BillingService billing) {
        this.billing = billing;
    }
}

Setting the Default with @Primary — and Its Blast Radius

@Primary declares the default bean for a type across the whole context. Plain injection points resolve to it without further annotation, while exceptional callers override with @Qualifier. It shines when one implementation is obviously the common case — the live payment provider versus the sandbox stub, the real clock versus the fixed test clock. One annotation settles every undecided injection point at once.

That global power is exactly why @Primary demands restraint. Two primaries of the same type fail fast, but one wrong primary fails silently: the context loads, health checks pass, and the wrong implementation serves traffic. The billing incident in this article is that story — a guessed @Primary wired the wrong provider while every dashboard stayed green. Mark a bean primary only when you'd bet the business on it being the default, and say so in a comment naming the exceptions.

Choose between the two with a simple rule. Caller-specific choice goes to @Qualifier; codebase-wide default goes to @Primary; both together means the qualifier wins at its own point. Never stack them as guesses during debugging — apply one, re-run, and assert the wired type in a context test. A test like assertThat(context.getBean(BillingService.class)).isInstanceOf(StripeBillingService.class) turns silent miswiring into a build failure.

// One default for the whole context — use sparingly
@Service
@Primary
public class StripeBillingService implements BillingService { }

// Every plain injection now resolves to Stripe;
// exceptional callers still override with @Qualifier("paypalBilling")
@Service
public class CheckoutService {
    private final BillingService billing;

    public CheckoutService(BillingService billing) {
        this.billing = billing;
    }
}

Component-Scan Gaps: The Bean Exists but Spring Never Looks

Component scanning starts at the package of your @SpringBootApplication class and covers everything below it. Classes in sibling or parent packages are invisible no matter how many stereotypes they carry. This bites during refactors that move the app class into a submodule, multi-module builds where a library package sits outside the root, and copy-pasted starters whose package doesn't match yours. The symptom is maddening: the annotation is right there, the code compiles, and Spring insists the bean doesn't exist.

Diagnose with packages, not annotations. Compare the app class package against the implementation's package with two find commands; if the implementation isn't under the root, you've found it. The actuator beans endpoint confirms from the runtime side — grep it for your class and expect no hit. Resist the urge to scatter @ComponentScan across configuration classes; competing scan roots interact badly and sweep up test doubles. One root, declared once, at the top of your package tree.

When code genuinely lives elsewhere — a shared company library — widen deliberately with scanBasePackages and review that line like API surface, because it is. Document why the external package is included and what it contributes. Better still, have the library ship an auto-configuration so consumers get beans without widening scans at all. The rule that prevents recurrence: the app class stays at the root, and every scan widening carries a comment with its reason.

// com.acme.App sits above everything it should wire
package com.acme;

@SpringBootApplication // scans com.acme.** by default
public class App { }

// Explicit widening when code must live elsewhere — review this line
@SpringBootApplication(scanBasePackages = {"com.acme", "com.shared.lib"})
public class WidenedApp { }

Circular Dependencies: Why Constructor Cycles Fail So Loudly

Constructor cycles — A needs B needs A — fail with BeanCurrentlyInCreation, and the nested chain prints the loop for you. Constructors are honest: they demand the dependency before the object exists, so a loop is unbuildable by construction. That's a feature, not a limitation. The error is telling you the design has a knot, and papering over it with field injection just moves the knot somewhere darker.

Break the loop by removing one edge, not by hiding it. The cleanest cut is usually events: A publishes OrderPlaced and B listens, so A no longer depends on B at all. Alternatives fit other shapes — ObjectProvider<B> defers one lookup until first use, @Lazy on one parameter builds a proxy, and splitting shared logic into a third service C that both depend on dissolves the knot entirely. Pick the option that matches the domain: events for notifications, providers for genuinely optional collaborators, extraction for shared logic both sides wanted.

What you must not do is switch to field injection to make the error vanish. Field-injected cycles start up and then fail unpredictably — nulls in some paths, half-wired proxies in others — because the container can no longer enforce build order. Spring Boot 2.6+ bans circular references by default precisely to force the honest failure. Keep constructors, read the loop from the exception, and cut one edge for real.

// Break the loop: one edge becomes an event
@Service
public class OrderService {
    private final ApplicationEventPublisher events;

    public OrderService(ApplicationEventPublisher events) {
        this.events = events;
    }

    public void place(Order o) {
        events.publishEvent(new OrderPlaced(o)); // AuditService listens
    }
}

@Service
public class AuditService {
    private final OrderService orders; // one-directional now

    public AuditService(OrderService orders) {
        this.orders = orders;
    }
}

Field vs Constructor Injection: End the Debate for Good

Constructor injection lists every dependency in the signature, marks fields final, and works with plain new in unit tests. The compiler enforces completeness: you cannot build the object without its collaborators. New team members read the constructor and know what the class needs; reviewers see added dependencies as signature changes, not hidden field edits. For wiring errors specifically, constructors fail at startup with the exact missing type instead of null-pointering at 2 AM.

Field injection — @Autowired on a private field — hides all of that. Dependencies are invisible to the compiler, untestable without reflection or a container, and mutable by anyone with a setter or a test utility. It also masks cycles: two field-injected services start fine and then NPE in whichever method runs first. The startup error you avoided was the cheap one; the production null is the expensive one. Lombok's @RequiredArgsConstructor removes the verbosity objection entirely — you write the final fields and get the constructor free.

Standardize on one style and enforce it. Ban field and setter @Autowired with a review rule or an ArchUnit test, require final fields, and let constructor injection be the only path. Mixed codebases pay a steady tax: every wiring failure takes longer because the reader must check three injection styles per class. One style means the diagnosis in this article always starts at the constructor, where the answer lives.

// Constructor injection: explicit, final, testable without Spring
@Service
public class CheckoutService {
    private final BillingService billing;
    private final OrderRepository orders;

    public CheckoutService(BillingService billing, OrderRepository orders) {
        this.billing = billing;
        this.orders = orders;
    }
}

// Plain unit test — no container, no reflection
@Test
void chargesOnPlace() {
    var svc = new CheckoutService(new FakeBilling(), new FakeOrders());
    assertDoesNotThrow(() -> svc.place(order()));
}