spring-projects/spring-framework · error · NoUniqueBeanDefinitionException

No qualifying bean of type '{}' available: expected single m

Error message

No qualifying bean of type '{}' available: expected single matching bean but found {}: {}

What it means

NoUniqueBeanDefinitionException from BeanFactoryUtils.uniqueBean when resolving a single bean by type yields more than one candidate. This private helper backs beanOfType(...) overloads that require a unique instance. The message lists the count and the matching bean names so you can disambiguate.

Source

Thrown at spring-beans/src/main/java/org/springframework/beans/factory/BeanFactoryUtils.java:549

		}
		return StringUtils.toStringArray(merged);
	}

	/**
	 * Extract a unique bean for the given type from the given Map of matching beans.
	 * @param type the type of bean to match
	 * @param matchingBeans all matching beans found
	 * @return the unique bean instance
	 * @throws NoSuchBeanDefinitionException if no bean of the given type was found
	 * @throws NoUniqueBeanDefinitionException if more than one bean of the given type was found
	 */
	private static <T> T uniqueBean(Class<T> type, Map<String, T> matchingBeans) {
		int count = matchingBeans.size();
		if (count == 1) {
			return matchingBeans.values().iterator().next();
		}
		else if (count > 1) {
			throw new NoUniqueBeanDefinitionException(type, matchingBeans.keySet());
		}
		else {
			throw new NoSuchBeanDefinitionException(type);
		}
	}

}

View on GitHub (pinned to 69bf83ad71)

Solutions

Mark one candidate @Primary so type-resolution picks it.
Narrow the injection with @Qualifier("beanName").
Collapse the duplicate definitions (remove one @Bean method or @Component).
If both are legitimately needed, inject List<MyService> or ObjectProvider<MyService> instead of a single instance.

Example fix

// before
@Bean FooService a() { ... }
@Bean FooService b() { ... }
// getBean(FooService.class) -> NoUniqueBeanDefinitionException

// after
@Bean @Primary FooService a() { ... }
@Bean FooService b() { ... }

Defensive patterns

Strategy: validation

Validate before calling

// Assert a unique bean exists before lookup
String[] names = beanFactory.getBeanNamesForType(MyService.class);
if (names.length > 1) {
    throw new IllegalStateException("ambiguous MyService beans: " + Arrays.toString(names));
}

Type guard

static boolean isUnique(ListableBeanFactory bf, Class<?> t) {
    return bf.getBeanNamesForType(t).length == 1;
}

Try / catch

try {
    MyService s = bf.getBean(MyService.class);
} catch (NoUniqueBeanDefinitionException ex) {
    // disambiguate explicitly
    s = bf.getBean("primaryService", MyService.class);
}

Prevention

Mark a canonical implementation @Primary by convention.
Use @Qualifier at injection points that could be ambiguous.
Add a test asserting exactly one bean per interface.

When it happens

Trigger: Calling beanFactory.getBean(MyService.class) / BeanFactoryUtils.beanOfType(factory, MyService.class) when two or more beans implement MyService and none is marked @Primary or selected via @Qualifier.

Common situations: Adding a second implementation of an interface (e.g. a test stub plus the real bean); multiple DataSource/PlatformTransactionManager beans without @Primary; @ConditionalOnMissingBean misconfiguration producing duplicates.

Related errors

AI-assisted analysis of spring-projects/spring-framework@69bf83ad71 (2026-08-09). Data as JSON: /api/errors/322f1f35271e57ba. Report an issue: GitHub.