Fixing “Error creating bean with name” in Spring Boot

Error creating bean with name 'orderService' is Spring reporting that it could not construct one of your components, and the line itself is almost never the problem. The actual cause is further down the stack trace, after several Caused by: lines, and it is one of six things: a dependency Spring cannot find, two beans depending on each other, a configuration value missing, a constructor that threw, a database it cannot reach, or two beans with the same name. Find the last Caused by, and the fix follows.

Step 1: find the real cause#

org.springframework.beans.factory.UnsatisfiedDependencyException:
  Error creating bean with name 'orderController': Unsatisfied dependency expressed through constructor parameter 0;
  nested exception is ...BeanCreationException: Error creating bean with name 'orderService': ...
Caused by: org.springframework.beans.factory.NoSuchBeanDefinitionException:
  No qualifying bean of type 'com.shop.PaymentGateway' available: expected at least 1 bean which qualifies as autowire candidate.

Read from the bottom up. The top line is the outermost bean that failed; each nested line is one dependency deeper; the final Caused by is what went wrong. Spring Boot also prints a plain-language summary under APPLICATION FAILED TO START with a Description and an Action; read that first, it is often enough.

Cause 1: no qualifying bean#

No qualifying bean of type 'com.shop.PaymentGateway' available

A constructor asks for a type and Spring has no bean of it. Usually one of:

• The class is missing @Service, @Component, @Repository or a @Bean method.
• The class is in a package Spring does not scan. By default scanning starts from the package of the main application class; anything above or beside it is invisible. Move the class, or add @ComponentScan.
• The type is an interface with no implementation on the classpath, or the implementation is behind a @Profile or @ConditionalOn... that is not active.
• A starter dependency is missing, so the auto-configuration that would create the bean never ran.

@Service                                     // this annotation was missing
public class StripeGateway implements PaymentGateway { ... }

Cause 2: more than one bean#

expected single matching bean but found 2: stripeGateway,paypalGateway

Two implementations of the same interface. Tell Spring which one: @Primary on the default, or @Qualifier("stripeGateway") at the injection point.

Cause 3: circular reference#

The dependencies of some of the beans in the application context form a cycle:
   orderService -> paymentService -> orderService

A needs B and B needs A, and with constructor injection neither can be built first. The right fix is structural: extract the shared part into a third class both depend on, or make one direction an event rather than a call. The quick fix is @Lazy on one of the constructor parameters, which defers that dependency until first use. Spring Boot disables the old silent workaround by default because cycles are almost always a design problem.

Cause 4: a missing property#

Could not resolve placeholder 'payment.api.key' in value "${payment.api.key}"

A @Value or a @ConfigurationProperties field needs a setting that is not in application.properties, the environment, or the active profile’s file. Add it, provide a default with ${payment.api.key:}, or check that the profile you expect is actually active — a value defined in application-prod.properties is absent when running without spring.profiles.active=prod.

Cause 5: the constructor or @PostConstruct threw#

Caused by: java.lang.IllegalStateException: API key must not be blank
Caused by: java.lang.NullPointerException: ...

The bean’s own code failed during construction. The bottom of the trace is an ordinary exception with a line number in your class. Fix it as you would any exception; the Spring wrapping is incidental.

Cause 6: the database is unreachable#

Error creating bean with name 'entityManagerFactory'
Caused by: ...CommunicationsException: Communications link failure
Caused by: java.net.ConnectException: Connection refused

Any JPA repository pulls in the data source, and if the database is down, the URL is wrong or the credentials are wrong, every bean that touches persistence fails. The last line says which: connection refused (not running, wrong host or port), access denied (credentials), unknown database (wrong name). Check spring.datasource.url and that the database is actually up.

Cause 7: duplicate bean names#

The bean 'userService', defined in class path resource [...], could not be registered.
A bean with that name has already been defined

Two classes named UserService in different packages, or a @Bean method with the same name as a component. Rename one, or set spring.main.allow-bean-definition-overriding=true if the override is deliberate, which it rarely is.

Reading the Boot summary#

***************************
APPLICATION FAILED TO START
***************************

Description:
Parameter 0 of constructor in com.shop.OrderService required a bean of type 'com.shop.PaymentGateway' that could not be found.

Action:
Consider defining a bean of type 'com.shop.PaymentGateway' in your configuration.

Spring Boot’s failure analysers produce this for the common cases. When it appears, it is the most useful thing in the log; when it does not, fall back to the last Caused by.

Where to go next#

• Spring Boot Whitelabel Error Page — the runtime counterpart.
• Java and the Spring Framework — how beans and injection work.
• NullPointerException explained — the most common constructor failure.