Fix UnsatisfiedDependencyException in Spring Applications
Read the nested messages of UnsatisfiedDependencyException to find the real problem behind a failed constructor, setter or field injection.

This is one of the longest stack traces in the Spring world, and the length is deceptive. Each bean that depends on a failing bean adds one UnsatisfiedDependencyException around the exception below it, so a failure three layers down produces three wrappers:
org.springframework.beans.factory.UnsatisfiedDependencyException: Error creating bean with name 'orderController': Unsatisfied dependency expressed through constructor parameter 0: Error creating bean with name 'orderService': Unsatisfied dependency expressed through constructor parameter 0: No qualifying bean of type 'dev.javahacks.shop.PaymentGateway' available: expected at least 1 bean which qualifies as autowire candidate.Read it from the right. The last sentence is the problem; everything before it is the route Spring took to discover it. The wrapper lives in the creation sequence described in how the Spring container works.
Parse the message
| Fragment | Meaning |
|---|---|
Error creating bean with name 'orderController' | The bean that could not be built |
constructor parameter 0 | Which injection point failed (constructor, setter or field, with name or index) |
Error creating bean with name 'orderService' | The next bean down the chain |
No qualifying bean of type ... | The root cause |
The route is orderController needs orderService needs PaymentGateway. Only the last link is broken.
The three root causes
After the final colon, you will almost always find one of these:
| Root cause text | What it means | Fix |
|---|---|---|
| "No qualifying bean of type ... available" | Nothing matches | No qualifying bean of type |
| "expected single matching bean but found 2" | More than one match | [NoUniqueBeanDefinitionException](/library/nouniquebeandefinitionexception-fix-qualifier) |
BeanCreationException or another exception from the dependency | The dependency was found and failed while initializing | [BeanCreationException](/library/beancreationexception-error-creating-bean-fix-name) |
Find the innermost cause in a long trace
A long trace can run to hundreds of lines, but you do not need to read them. Search the log for the last line beginning Caused by::
grep -n "Caused by:" app.log | tail -3Open the last result. In an IDE console, enable "fold lines" on the framework packages. If the cause is a NullPointerException or an IllegalStateException from your own constructor, the bug is in your code and Spring only reported it.
A realistic example
@Service
class OrderService {
OrderService(PaymentGateway gateway, Clock clock) { }
}If no Clock bean exists in your configuration, the exception names constructor parameter 1 and type java.time.Clock. Spring Boot does not provide a Clock bean, so declare one:
@Bean
Clock clock() {
return Clock.systemUTC();
}The parameter index is zero-based, which trips people up: "parameter 1" is the second argument.
Field and setter variants
For field injection the message says Unsatisfied dependency expressed through field 'gateway', and for setters through method 'setGateway' parameter 0. The cause categories are the same. Prefer constructor injection so the list of dependencies is visible in one place, and an unsatisfiable one fails the bean's creation immediately.
The wrapper and the failure analyzer say the same thing differently
UnsatisfiedDependencyException is the exception Spring throws when it cannot supply a constructor argument or an injected field. In a Spring Boot application the failure analyzer turns it into a short report, and the two forms name the same problem. The report from a service whose dependency has no implementation reads:
Parameter 0 of constructor in dev.javahacks.lab.NeedsPricing required a bean of type 'dev.javahacks.lab.PricingService' that could not be found.The raw exception, which appears in logs of a test or an application that does not use the analyzer, reads:
org.springframework.beans.factory.UnsatisfiedDependencyException: Error creating bean with name 'needsPricing':
Unsatisfied dependency expressed through constructor parameter 0:
No qualifying bean of type 'dev.javahacks.lab.PricingService' availableBoth identify the bean being created (needsPricing), the injection point (constructor parameter 0) and the missing type. The first line of the second form is the wrapper. What follows Unsatisfied dependency expressed through is the real information, and the cause may sit several Caused by levels down when the dependency itself failed to build, which is the case for the long chains in the main section.
Reproduce the three causes in a test
A slice test can reproduce each cause in a second, which is faster than starting the application, and the same test becomes the regression guard.
class WiringTest {
@Test
void missingBeanFailsWithTheTypeInTheMessage() {
try (var ctx = new AnnotationConfigApplicationContext()) {
ctx.register(NeedsPricing.class);
assertThatThrownBy(ctx::refresh)
.isInstanceOf(UnsatisfiedDependencyException.class)
.hasMessageContaining("PricingService");
}
}
@Test
void ambiguousBeanFailsWithBothCandidates() {
try (var ctx = new AnnotationConfigApplicationContext()) {
ctx.register(NeedsPricing.class, PricingA.class, PricingB.class);
assertThatThrownBy(ctx::refresh)
.hasMessageContaining("expected single matching bean but found 2");
}
}
}A plain AnnotationConfigApplicationContext loads only the classes you register, so there is no ambiguity about what the container holds. That clarity is why the pattern is useful for debugging wiring: remove everything but the failing bean and its dependency, and you see the minimal case.
Constructor, field and setter forms
The same exception covers all three injection styles, and constructor injection gives the clearest report because the message names the parameter. Field injection names the field: Unsatisfied dependency expressed through field 'pricing'. Setter injection names the method. Prefer constructor injection for required dependencies for this reason, and because it makes the dependency visible in tests that construct the class directly, without a container.
// Field injection hides the dependency, and the class cannot be built without Spring
@Autowired private PricingService pricing;
// Constructor injection states it, and a test can pass a fake
NeedsPricing(PricingService pricing) { this.pricing = pricing; }A circular dependency looks like this
Two beans that need each other cannot both be built first. Spring Boot 2.6 and later forbids it by default and says so with the cycle spelled out, which turns a puzzling failure into a diagram.
The dependencies of some of the beans in the application context form a cycle:
┌─────┐
| orderService defined in file [...]
↑ ↓
| invoiceService defined in file [...]
└─────┘The fix is to break the cycle in the design, not to allow it. Extract the behaviour both need into a third bean that depends on neither, or replace one direct call with an event. The setting spring.main.allow-circular-references=true exists, and using it hides a design problem and invites partially initialised beans at run time.
Read errors in a long chain from the bottom
Large applications report chains four or five wrappers deep. Scroll to the last Caused by and read that one, then walk up only as far as you need to know which bean was involved. The deepest cause is a missing class, a bad property, or an exception from your own @PostConstruct. The wrappers above it are the path Spring took to get there and are rarely the problem.
Fix the dependency, then guard the wiring
After the fix, add one test that loads the full context and fails if any dependency is unresolved. It is the cheapest protection against this whole class of error, because it runs wherever the unit tests run and needs no database when the data source is replaced.
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.NONE)
class ContextLoadsTest {
@Test
void contextStarts() { }
}An empty test method is enough: the context failing to start fails the test, with the same failure report as production. Run it on every pull request. A missing bean introduced by a refactoring is then caught before merge instead of after deployment.
Where this does not apply
If the trace begins with BeanCreationException and has no Unsatisfied dependency line, no injection failed: the bean was found and failed in its own initialization. If it appears only in tests, check whether a slice test loads the dependency; the pattern is in a practical testing strategy. See the Spring dependency injection reference for the injection variants. The Spring Framework API documentation documents the behavior in detail.


