Fix No Qualifying Bean of Type in Spring Boot Applications
Find why Spring cannot supply a bean of the type you asked for, from component scanning and missing annotations to profiles and test slices.

The context fails to start and the report names the exact injection point:
Description:
Parameter 0 of constructor in dev.javahacks.shop.OrderService required a bean of type 'dev.javahacks.shop.PaymentGateway' that could not be found.
Action:
Consider defining a bean of type 'dev.javahacks.shop.PaymentGateway' in your configuration.The container looked for a bean assignable to PaymentGateway and found none. Walk the causes in order, most likely first. The container's lookup rules are in how the Spring container works, and the same problem at framework level is [NoSuchBeanDefinitionException](/library/nosuchbeandefinitionexception-fix-spring).
Cause 1: the class is not a bean
class StripeGateway implements PaymentGateway { /* ... */ } // no annotationAdd a stereotype:
@Component
class StripeGateway implements PaymentGateway { /* ... */ }Use @Service, @Repository or @Component, or declare a @Bean method in a @Configuration class. A class from a third-party library cannot be annotated, so you register it with @Bean.
Cause 2: the class is outside the scan
The scan starts at the package of the @SpringBootApplication class. A bean in com.other.payments is not found when the application is in dev.javahacks.shop. Move it, or add @Import(StripeGateway.class) or @ComponentScan. Repositories have their own scan: Spring Data scans the application package for interfaces, and a repository elsewhere needs @EnableJpaRepositories(basePackages = ...).
Cause 3: a profile or condition removed it
@Component
@Profile("prod")
class StripeGateway implements PaymentGateway { /* ... */ }Without the prod profile, there is no PaymentGateway. Check spring.profiles.active, and provide a fallback bean for other profiles if the application needs to start without one. @ConditionalOnProperty and @ConditionalOnMissingBean fail the same way. Run with --debug to read the condition report.
Cause 4: the interface has no implementation
Spring cannot inject an interface that nothing implements. This also happens after a refactoring that renamed the implementation and left it unannotated. Search the codebase for classes implementing the interface.
Cause 5: a test slice does not include it
@WebMvcTest loads controllers and web components only. If the controller needs OrderService, the test fails with this error until you supply it:
@WebMvcTest(OrderController.class)
class OrderControllerTest {
@MockitoBean OrderService orders;
}@DataJpaTest loads repositories and an in-memory or test database, not your services. The pattern is covered in a practical testing strategy, and the load failure itself in Failed to load ApplicationContext.
Cause 6: generics or a proxy changed the type
A bean typed as a generic interface, Converter<Order, Dto>, only matches an injection point with compatible type arguments. A JDK proxy implements the interfaces but not the class, so injecting by the concrete class fails when the bean is proxied with interfaces. Inject the interface, or use class-based proxying.
Quick check
| Question | How to answer |
|---|---|
| Is the class a bean at all? | Annotation or @Bean method present |
| Is it scanned? | Package starts with the application package |
| Is it active? | Profile and conditions satisfied |
| Is it a test? | Slice loads it, or you mock it |
The two messages for the two situations
"No qualifying bean" can mean zero candidates or too many, and Spring Boot's failure analyzer words them differently. Both were reproduced with a service whose constructor takes a PricingService interface, on Spring Boot 4.0.9.
With no implementation registered:
APPLICATION FAILED TO START
Description:
Parameter 0 of constructor in dev.javahacks.lab.NeedsPricing required a bean of type 'dev.javahacks.lab.PricingService' that could not be found.
Action:
Consider defining a bean of type 'dev.javahacks.lab.PricingService' in your configuration.The report names the class and parameter that needs the bean, and the exact type. From there the six causes in this post are a checklist: is there a class that implements the type, is it annotated, is it inside the scan, is a profile or condition removing it, is this a test slice that does not load it, and does generic type information differ.
With two implementations:
Parameter 0 of constructor in dev.javahacks.lab.NeedsPricingToo required a single bean, but 2 were found:
- pricingA: defined in URL [jar:nested:.../PricingA.class]
- pricingB: defined in URL [jar:nested:.../PricingB.class]
This may be due to missing parameter name informationThis is the other face of the same family of errors, and the fix is the opposite: not to create a bean but to choose one. The report lists the candidates and where each was defined, so you can see at once whether the second came from your code or a library. Choose with @Primary on the default implementation, with @Qualifier("pricingA") at the injection point, or by naming the constructor parameter after the bean when parameter names are retained (the "missing parameter name" hint refers to compiling with -parameters, which Spring Boot's Maven and Gradle plugins enable).
@Service
class NeedsPricingToo {
NeedsPricingToo(@Qualifier("pricingA") PricingService pricing) { }
}Ask the context what it has
When the cause is not obvious, query the container. Print every bean of the type, and the beans in a package.
@Component
class BeanReport implements ApplicationRunner {
private final ApplicationContext ctx;
BeanReport(ApplicationContext ctx) { this.ctx = ctx; }
@Override
public void run(ApplicationArguments args) {
System.out.println("PricingService beans: " + Arrays.toString(ctx.getBeanNamesForType(PricingService.class)));
Arrays.stream(ctx.getBeanDefinitionNames())
.filter(n -> n.toLowerCase().contains("pricing"))
.forEach(n -> System.out.println("bean: " + n));
}
}An empty array for the type confirms that no implementation was registered, and the next question is why. Boot also writes a conditions report with --debug, which lists every auto-configuration that did not match and states why. For a bean that should come from a starter, the negative matches section often names the missing class or property directly.
The mistakes behind most reports
The first is a class without a stereotype annotation. A plain class PricingServiceImpl implements PricingService is not a bean until it has @Service, @Component or a @Bean method. The second is a scan boundary: Boot scans the package of the @SpringBootApplication class and its sub-packages, so a class in dev.other is invisible when the application class is in dev.javahacks. Move the application class up, or add scanBasePackages. The third is the test slice: @WebMvcTest loads controllers and web components only, so a controller that needs a service fails in the test even though the application starts. Add @MockitoBean PricingService pricing to the test, or import the configuration that provides it.
@WebMvcTest(OrderController.class)
class OrderControllerTest {
@MockitoBean PricingService pricing; // the slice does not scan @Service classes
}Optional dependencies are another way out. If the bean really is optional, inject ObjectProvider<PricingService> or Optional<PricingService>, and the context starts without it; make that choice on purpose, since it turns a startup failure into a null check at run time.
A fast way to decide which fix applies
Three questions sort nearly every case. Does the report say "that could not be found"? Then no bean exists for the type, and the work is to find out why your class was not registered. Does it say "required a single bean, but N were found"? Then there is a choice to make, and the report already lists the candidates. Does it appear only in a test? Then the slice is narrower than the application, and the missing piece is a mock or an import. Answering these in order takes a minute and avoids the usual detour of adding annotations at random until the error moves.
Where this does not apply
If the error says "expected single matching bean but found 2", you have too many beans, not too few; see [NoUniqueBeanDefinitionException](/library/nouniquebeandefinitionexception-fix-qualifier). The Spring Framework reference describes scanning, and the Spring Boot documentation explains the recommended package layout.


