{"record":{"id":"b350732d70dd87b0","repo":"spring-projects/spring-framework","slug":"error-registering-bean-definition","errorCode":null,"errorMessage":"Error registering bean definition","messagePattern":"Error registering bean definition","errorType":"exception","errorClass":"BeanDefinitionStoreException","httpStatus":null,"severity":"error","filePath":"spring-beans/src/main/java/org/springframework/beans/factory/config/PlaceholderConfigurerSupport.java","lineNumber":253,"sourceCode":"\t\tthis.beanFactory = beanFactory;\n\t}\n\n\tprotected void doProcessProperties(ConfigurableListableBeanFactory beanFactoryToProcess,\n\t\t\tStringValueResolver valueResolver) {\n\n\t\tBeanDefinitionVisitor visitor = new BeanDefinitionVisitor(valueResolver);\n\n\t\tString[] beanNames = beanFactoryToProcess.getBeanDefinitionNames();\n\t\tfor (String curName : beanNames) {\n\t\t\t// Check that we're not parsing our own bean definition,\n\t\t\t// to avoid failing on unresolvable placeholders in properties file locations.\n\t\t\tif (!(curName.equals(this.beanName) && beanFactoryToProcess.equals(this.beanFactory))) {\n\t\t\t\tBeanDefinition bd = beanFactoryToProcess.getBeanDefinition(curName);\n\t\t\t\ttry {\n\t\t\t\t\tvisitor.visitBeanDefinition(bd);\n\t\t\t\t}\n\t\t\t\tcatch (Exception ex) {\n\t\t\t\t\tthrow new BeanDefinitionStoreException(bd.getResourceDescription(), curName, ex.getMessage(), ex);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\t// Resolve placeholders in alias target names and aliases as well.\n\t\tbeanFactoryToProcess.resolveAliases(valueResolver);\n\n\t\t// Resolve placeholders in embedded values such as annotation attributes.\n\t\tbeanFactoryToProcess.addEmbeddedValueResolver(valueResolver);\n\t}\n\n}\n","sourceCodeStart":235,"sourceCodeEnd":266,"githubUrl":"https://github.com/spring-projects/spring-framework/blob/69bf83ad716d0cfc4b0520a19b4d8b24c79d1538/spring-beans/src/main/java/org/springframework/beans/factory/config/PlaceholderConfigurerSupport.java#L235-L266","documentation":"Wrapped as a BeanDefinitionStoreException (message prefix 'Error registering bean definition') inside PlaceholderConfigurerSupport.doProcessProperties() when BeanDefinitionVisitor.visitBeanDefinition(bean) throws while a placeholder configurer processes each bean definition. The underlying cause's message is appended, so the real problem is usually an unresolvable ${placeholder} or a type-resolution error during placeholder substitution. This is the umbrella error thrown by PropertyPlaceholderConfigurer / PropertySourcesPlaceholderConfigurer when applying replacements fails for a given bean.","triggerScenarios":"A bean definition value containing ${some.key} where 'some.key' is missing from every property source and ignoreUnresolvablePlaceholders is false (the default). Placeholders in bean names, aliases, or property values that the visitor cannot resolve. A nested BeansException (e.g. type conversion after substitution) during the visit.","commonSituations":"Properties file missing or not on the classpath, so the placeholder source is empty. Typo in the placeholder key vs. the properties key. Profile-specific properties not activated. Using ${...} in a value but only registering the PropertySourcesPlaceholderConfigurer conditionally. Circular or recursive placeholder references.","solutions":["Read the wrapped cause message to find the exact placeholder key that failed, then add that key to your properties file or Environment.","Register/enable a PropertySourcesPlaceholderConfigurer (or context:property-placeholder) pointed at the correct locations and ensure those files resolve on the classpath.","If the placeholder is optional, set ignoreUnresolvablePlaceholders=true or give an inline default: value=\"${some.key:defaultValue}\".","Verify active profiles / environment so the right PropertySource is loaded before bean definitions are post-processed."],"exampleFix":"<!-- before (broken): key not found -->\n<property name=\"url\" value=\"jdbc:${jdbc.dbname}\"/>\n<!-- after: add inline default -->\n<property name=\"url\" value=\"jdbc:${jdbc.dbname:defaultdb}\"/>","handlingStrategy":"try-catch","validationCode":"// Before refresh, verify all ${...} placeholders resolve against the Environment\nBeanDefinitionRegistry registry = (BeanDefinitionRegistry) beanFactory;\nfor (String name : beanFactory.getBeanDefinitionNames()) {\n    BeanDefinition bd = beanFactory.getBeanDefinition(name);\n    // scan resolved values / placeholders via a PropertyResolver dry-run if available\n}","typeGuard":"// No type guard; this is a runtime resolution failure. Validate keys exist instead.\nstatic boolean placeholderResolves(Environment env, String key) {\n    return env.containsProperty(key);\n}","tryCatchPattern":"try {\n    context.refresh();\n} catch (BeanDefinitionStoreException ex) {\n    Throwable cause = ex.getMostSpecificCause();\n    if (cause instanceof IllegalArgumentException iae && iae.getMessage().contains(\"placeholder\")) {\n        // extract the unresolved key and add it, then retry refresh\n    }\n    throw ex;\n}","preventionTips":["Keep a single source of truth for property keys and reference it from both config and properties files.","Set ignoreUnresolvablePlaceholders=true only when chaining multiple configurers; otherwise prefer inline defaults like ${key:fallback}.","Add a startup test asserting context.refresh() succeeds for each active profile.","Use an IDE/CI placeholder-usage check to catch typos between ${key} and the properties file."],"tags":["spring","placeholder","configuration","bean-definition","properties"],"backgroundTag":null,"analyzedSha":"69bf83ad716d0cfc4b0520a19b4d8b24c79d1538","analyzedAt":"2026-08-09T15:32:58.770Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}