ConflictingBeanDefinitionException: Annotation-specified bean name 'userService' for bean class

Q: Explicitly name the beans

When to use: Use this if you legitimately need two implementations of the same interface.. By default, Spring uses the lowercase class name as the bean name. If you have 'UserService' and 'UserServiceImpl', both register as 'userService'. Give them unique names.

Q: Delete the duplicate class

When to use: Use this if you accidentally created two classes with the same name in different packages.. Sometimes developers copy-paste a class into a different folder. Spring sees both and gets confused. Delete the one you don't need.

Q: Use @Primary or @Qualifier

When to use: Use this when you have multiple beans of the same type and need to tell Spring which one to inject by default.. If you have multiple beans, annotate the main one with @Primary so Spring chooses it. Or use @Qualifier at the injection point.

🔴 The Error You're Seeing

Confirm this matches your console output. If it does, you're in the right place.

ERROR LOG

2026-02-14 20:30:11.500 ERROR 8842 --- [           main] o.s.boot.SpringApplication               : Application run failed

org.springframework.context.annotation.ConflictingBeanDefinitionException: Annotation-specified bean name 'userService' for bean class [com.devinhyderabad.service.UserServiceImpl] conflicts with existing, incompatible bean definition of same name and class [com.devinhyderabad.service.UserService]

⚡ Quick Fix Works 80% of the time

Give one of the beans a distinct name in the @Service annotation.

@Service("userServiceImpl")
public class UserServiceImpl implements UserService { ... }

🧠 Why this Happens

Tap to expand the deep technical explanation

Spring scans your project and finds two different Java classes that are both trying to register themselves as a Spring Bean using the exact same name. Spring cannot decide which one to use, so it crashes.

The HITEC City Parking Spot Analogy:

It is like two employees in a company having the exact same email address. The mail server (Spring) doesn't know which inbox to deliver the message to, so it rejects the setup entirely.

🔁 How to Reproduce Confirm this is your error

Create two classes annotated @Service/@Component that resolve to the same bean name (for example two classes called UserService in different packages), then start the app. Spring throws ConflictingBeanDefinitionException.

🛠️ Solutions (3 Ways to Fix)

Solution 1✓ Most common cause

Explicitly name the beans

👉 Use this if you legitimately need two implementations of the same interface.

By default, Spring uses the lowercase class name as the bean name. If you have 'UserService' and 'UserServiceImpl', both register as 'userService'. Give them unique names.

@Service("primaryUserService")
public class UserServiceImpl implements UserService { ... }

@Service("secondaryUserService")
public class MockUserService implements UserService { ... }

Solution 2

Delete the duplicate class

👉 Use this if you accidentally created two classes with the same name in different packages.

Sometimes developers copy-paste a class into a different folder. Spring sees both and gets confused. Delete the one you don't need.

// Ensure only one class is annotated with @Service
// for the 'UserService' functionality.

Solution 3

Use @Primary or @Qualifier

👉 Use this when you have multiple beans of the same type and need to tell Spring which one to inject by default.

If you have multiple beans, annotate the main one with @Primary so Spring chooses it. Or use @Qualifier at the injection point.

@Service
@Primary // Spring will inject this one by default
public class UserServiceImpl implements UserService { ... }

// Or at injection point:
@Autowired
@Qualifier("secondaryUserService")
private UserService userService;

📋 Version Notes

Spring Boot 2.x

Allows bean overriding by default (spring.main.allow-bean-definition-overriding=true).

Spring Boot 3.x

Bean overriding is disabled by default. Conflicting names cause immediate startup failure.

🛡️ How to Prevent This Next Time

Stick to a strict naming convention. If you have an interface 'UserService', name the implementation 'UserServiceImpl' rather than 'UserService'.