{"record":{"id":"322f1f35271e57ba","repo":"spring-projects/spring-framework","slug":"no-qualifying-bean-of-type-available-expecte","errorCode":null,"errorMessage":"No qualifying bean of type '{}' available: expected single matching bean but found {}: {}","messagePattern":"No qualifying bean of type '(.+?)' available: expected single matching bean but found (.+?): (.+?)","errorType":"exception","errorClass":"NoUniqueBeanDefinitionException","httpStatus":null,"severity":"error","filePath":"spring-beans/src/main/java/org/springframework/beans/factory/BeanFactoryUtils.java","lineNumber":549,"sourceCode":"\t\t}\n\t\treturn StringUtils.toStringArray(merged);\n\t}\n\n\t/**\n\t * Extract a unique bean for the given type from the given Map of matching beans.\n\t * @param type the type of bean to match\n\t * @param matchingBeans all matching beans found\n\t * @return the unique bean instance\n\t * @throws NoSuchBeanDefinitionException if no bean of the given type was found\n\t * @throws NoUniqueBeanDefinitionException if more than one bean of the given type was found\n\t */\n\tprivate static <T> T uniqueBean(Class<T> type, Map<String, T> matchingBeans) {\n\t\tint count = matchingBeans.size();\n\t\tif (count == 1) {\n\t\t\treturn matchingBeans.values().iterator().next();\n\t\t}\n\t\telse if (count > 1) {\n\t\t\tthrow new NoUniqueBeanDefinitionException(type, matchingBeans.keySet());\n\t\t}\n\t\telse {\n\t\t\tthrow new NoSuchBeanDefinitionException(type);\n\t\t}\n\t}\n\n}\n","sourceCodeStart":531,"sourceCodeEnd":557,"githubUrl":"https://github.com/spring-projects/spring-framework/blob/69bf83ad716d0cfc4b0520a19b4d8b24c79d1538/spring-beans/src/main/java/org/springframework/beans/factory/BeanFactoryUtils.java#L531-L557","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\n@Bean FooService a() { ... }\n@Bean FooService b() { ... }\n// getBean(FooService.class) -> NoUniqueBeanDefinitionException\n\n// after\n@Bean @Primary FooService a() { ... }\n@Bean FooService b() { ... }","handlingStrategy":"validation","validationCode":"// Assert a unique bean exists before lookup\nString[] names = beanFactory.getBeanNamesForType(MyService.class);\nif (names.length > 1) {\n    throw new IllegalStateException(\"ambiguous MyService beans: \" + Arrays.toString(names));\n}","typeGuard":"static boolean isUnique(ListableBeanFactory bf, Class<?> t) {\n    return bf.getBeanNamesForType(t).length == 1;\n}","tryCatchPattern":"try {\n    MyService s = bf.getBean(MyService.class);\n} catch (NoUniqueBeanDefinitionException ex) {\n    // disambiguate explicitly\n    s = bf.getBean(\"primaryService\", MyService.class);\n}","preventionTips":["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."],"tags":["dependency-injection","bean-resolution","no-unique-bean"],"backgroundTag":null,"analyzedSha":"69bf83ad716d0cfc4b0520a19b4d8b24c79d1538","analyzedAt":"2026-08-09T15:32:58.770Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}