Spring BeanDefinitionStoreException

1. Overview

In this article, we will discuss the Spring org.springframework.beans.factory.BeanDefinitionStoreException – this is typically the responsibility of a BeanFactory when a bean definition is invalid, the loading of that bean is problematic. The article will discuss the most common causes of this exception along with the solution for each one.

2. Cause: java.io.FileNotFoundException

There are multiple possible causes that the BeanDefinitionStoreException may be caused by an underlying IOException:

2.1. IOException Parsing XML Document From ServletContext Resource

This usually happens in a Spring Web application, when a DispatcherServlet is set up in the web.xml for Spring MVC:

<servlet>  
   <servlet-name>mvc</servlet-name>  
   <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>  
</servlet>

By default, Spring will look for a file called exactly springMvcServlet-servlet.xml in the /WEB-INF directory of the web application.

If this file doesn’t exist, then the following exception will be thrown:

org.springframework.beans.factory.BeanDefinitionStoreException: 
Ioexception Parsing Xml Document from Servletcontext Resource [/WEB-INF/mvc-servlet.xml]; 
nested exception is java.io.FileNotFoundException: 
Could not open ServletContext resource [/WEB-INF/mvc-servlet.xml]

The solution is of course to make sure the mvc-servlet.xml file indeed exists under /WEB-INF; if it doesn’t, then a sample one can be created:

<?xml version="1.0" encoding="UTF-8"?>
<beans 
   xmlns="http://www.springframework.org/schema/beans"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="
      http://www.springframework.org/schema/beans 
      http://www.springframework.org/schema/beans/spring-beans-3.2.xsd" >

</beans>

2.2. IOException Parsing XML Document From Class Path Resource

This usually happens when something in the application points to an XML resource that doesn’t exist, or is not placed where it should be.

Pointing to such a resource may happen in a variety of ways.

Using for example Java Configuration, this may look like:

@Configuration
@ImportResource("beans.xml")
public class SpringConfig {...}

In XML, this will be:

<import resource="beans.xml"/>

Or even by creating an Spring XML context manually:

ApplicationContext context = new ClassPathXmlApplicationContext("beans.xml");

All of these will leads to the same exception if the file doesn’t exist:

org.springframework.beans.factory.BeanDefinitionStoreException: 
Ioexception Parsing Xml Document from Servletcontext Resource [/beans.xml]; 
nested exception is java.io.FileNotFoundException: 
Could not open ServletContext resource [/beans.xml]

The solution is create the file and to place it under the /src/main/resources directory of the project – this way, the file will exist on the classpath and it will be found and used by Spring.

3. Cause: Could Not Resolve Placeholder …

This error occurs when Spring tries to resolve a property but is not able to – for one of many possible reasons.

But first, the usage of the property – this may be used in XML:

... value="${some.property}" ...

The property could also be used in Java code:

@Value("${some.property}")
private String someProperty;

First thing to check is that the name of the property actually matches the property definition; in this example, we need to have the following property defined:

some.property=someValue

Then, we need to check where the properties file is defined in Spring – this is described in detail in my Properties with Spring Tutorial. A good best practice to follow is to have all properties files under the /src/main/resources directory of the application and to load them up via:

"classpath:app.properties"

Moving on from the obvious – another possible cause that Spring is not able to resolve the property is that there may be multiple PropertyPlaceholderConfigurer beans in the Spring context (or multiple property-placeholder elements)

If that is the case, then the solution is either collapsing these into a single one, or configuring the one in the parent context with ignoreUnresolvablePlaceholders.

4. Cause: java.lang.NoSuchMethodError

This error comes in a variety of forms – one of the more common ones is:

org.springframework.beans.factory.BeanDefinitionStoreException:
Unexpected exception parsing XML document from ServletContext resource [/WEB-INF/mvc-servlet.xml];
nested exception is java.lang.NoSuchMethodError:
org.springframework.beans.MutablePropertyValues.add (Ljava/lang/String;Ljava/lang/Object;)
Lorg/springframework/beans/MutablePropertyValues;

This usually happens when there are multiple versions of Spring on the classpath. Having an older version of Spring accidentally on the project classpath is more common than one would think – I described the problem and the solution for this in the Spring Security with Maven article.

In short, the solution for this error is simple – check all the Spring jars on the classpath and make sure that they all have the same version – and that version is 3.0 or above.

Similarly, the exception is not restricted to the MutablePropertyValues bean – there are several other incarnations of the same problem, caused by the same version inconsistency:

org.springframework.beans.factory.BeanDefinitionStoreException:
Unexpected exception parsing XML document from class path resource [/WEB-INF/mvc-servlet.xml];
- nested exception is java.lang.NoSuchMethodError:
org.springframework.util.ReflectionUtils.makeAccessible(Ljava/lang/reflect/Constructor;)V

5. Cause: java.lang.NoClassDefFoundError

A common problem, similarly related to Maven and the existing Spring dependencies is:

org.springframework.beans.factory.BeanDefinitionStoreException:
Unexpected exception parsing XML document from ServletContext resource [/WEB-INF/mvc-servlet.xml];
nested exception is java.lang.NoClassDefFoundError: 
org/springframework/transaction/interceptor/TransactionInterceptor

This occurs when transactional functionality is configured in the XML configuration:

<tx:annotation-driven/>

The NoClassDefFoundError means that the Spring Transactional support – namely spring-tx – does not exist on the classpath.

The solution is simple – spring-tx needs to be defined in the Maven pom:

<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-tx</artifactId>
    <version>4.1.0.RELEASE</version>
</dependency>

Of course this is not limited to the transaction functionality – a similar error is thrown if AOP is missing as well:

Exception in thread "main" org.springframework.beans.factory.BeanDefinitionStoreException: 
Unexpected exception parsing XML document from class path resource [/WEB-INF/mvc-servlet.xml]; 
nested exception is java.lang.NoClassDefFoundError: 
org/aopalliance/aop/Advice

The jars that are now required are: spring-aop (and implicitly aopalliance):

<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-aop</artifactId>
    <version>4.1.0.RELEASE</version>
</dependency>

6. Conclusion

At the end of this article, we should have a clear map to navigate the variety of causes and problems that may lead to a Bean Definition Store Exception as well as a good grasp on how to fix all of these problems.