spring-projects/spring-framework · error · NoSuchBeanDefinitionException

No matching {} bean found for qualifier '{}' - neither quali

Error message

No matching {} bean found for qualifier '{}' - neither qualifier match nor bean name match!

What it means

Thrown by qualifiedBeanOfType(ListableBeanFactory, Class, String) when no bean of the requested type has a matching qualifier AND no bean with the qualifier string as its bean name exists. This is the 'not found at all' outcome of qualifier resolution — neither the annotation-based qualifier match nor the bean-name fallback succeeded.

Source

Thrown at spring-beans/src/main/java/org/springframework/beans/factory/annotation/BeanFactoryAnnotationUtils.java:138

		String[] candidateBeans = BeanFactoryUtils.beanNamesForTypeIncludingAncestors(beanFactory, beanType);
		String matchingBean = null;
		for (String beanName : candidateBeans) {
			if (isQualifierMatch(qualifier::equals, beanName, beanFactory)) {
				if (matchingBean != null) {
					throw new NoUniqueBeanDefinitionException(beanType, matchingBean, beanName);
				}
				matchingBean = beanName;
			}
		}
		if (matchingBean != null) {
			return beanFactory.getBean(matchingBean, beanType);
		}
		else if (beanFactory.containsBean(qualifier) && beanFactory.isTypeMatch(qualifier, beanType)) {
			// Fallback: target bean at least found by bean name - probably a manually registered singleton.
			return beanFactory.getBean(qualifier, beanType);
		}
		else {
			throw new NoSuchBeanDefinitionException(qualifier, "No matching " + beanType.getSimpleName() +
					" bean found for qualifier '" + qualifier + "' - neither qualifier match nor bean name match!");
		}
	}

	/**
	 * Determine the {@link Qualifier#value() qualifier value} for the given
	 * annotated element.
	 * @param annotatedElement the class, method or parameter to introspect
	 * @return the associated qualifier value, or {@code null} if none
	 * @since 6.2
	 */
	public static @Nullable String getQualifierValue(AnnotatedElement annotatedElement) {
		Qualifier qualifier = AnnotationUtils.getAnnotation(annotatedElement, Qualifier.class);
		return (qualifier != null ? qualifier.value() : null);
	}

	/**
	 * Check whether the named bean declares a qualifier of the given name.

View on GitHub (pinned to 69bf83ad71)

Solutions

Verify the qualifier string exactly matches a @Qualifier value declared on one of the candidate bean definitions.
Ensure the target bean class has @Qualifier("expectedValue") on its class or @Bean method.
If relying on bean-name matching, confirm a bean with that exact name is registered.

Example fix

// before
// Injection point
@Autowired
@Qualifier("primary")
private DataSource ds;

// Bean — no @Qualifier declared
@Bean
DataSource myDataSource() { ... }

// after
@Bean
@Qualifier("primary")
DataSource myDataSource() { ... }

Defensive patterns

Strategy: validation

Validate before calling

// Verify a bean with the qualifier exists before resolving
ListableBeanFactory lbf = (ListableBeanFactory) beanFactory;
boolean found = false;
for (String name : lbf.getBeanNamesForType(beanType)) {
    // check for @Qualifier annotation or bean name match
    if (qualifier.equals(name) || hasQualifierAnnotation(name, qualifier, lbf)) {
        found = true; break;
    }
}
if (!found) {
    throw new IllegalStateException("No bean with qualifier '" + qualifier + "' of type " + beanType);
}

Try / catch

try {
    return BeanFactoryAnnotationUtils.qualifiedBeanOfType(lbf, beanType, qualifier);
} catch (NoSuchBeanDefinitionException ex) {
    // neither qualifier match nor bean name match
    // register the bean or fix the qualifier string
    throw new IllegalArgumentException("Invalid qualifier: " + qualifier, ex);
}

Prevention

Ensure @Qualifier is placed on the bean definition (class or @Bean method), not just on the injection point.
Double-check qualifier strings for typos — they must match exactly.
If relying on bean-name fallback, confirm the bean is registered under that exact name.

When it happens

Trigger: The qualifier string passed to qualifiedBeanOfType does not match any @Qualifier value on any bean of the type, and there is no bean with that string as its name. Lines 130-140 exhaust both the qualifier-match loop and the containsBean fallback before throwing.

Common situations: Typo in the qualifier string. The @Qualifier annotation was not placed on the bean definition (only on the injection point). Using a qualifier value that was intended but never declared on the target bean. Bean registered under a different name than expected.

Related errors

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