Skip to content
BSWEN
Blog

How to resolve IllegalStateException Unable to find @SpringBootConfiguration exception

Cowrie
Cowrie
Dev @ Bswen

1. The exception

When testing a Spring Boot application, you might encounter the IllegalStateException: Unable to find a @SpringBootConfiguration exception, as shown below:

Terminal window
java.lang.IllegalStateException: Unable to find a @SpringBootConfiguration, you need to use @ContextConfiguration or @SpringBootTest(classes=...) with your test


    at org.springframework.util.Assert.state(Assert.java:392)
    at org.springframework.boot.test.context.SpringBootTestContextBootstrapper.getOrFindConfigurationClasses(SpringBootTestContextBootstrapper.java:173)
    at org.springframework.boot.test.context.SpringBootTestContextBootstrapper.processMergedContextConfiguration(SpringBootTestContextBootstrapper.java:133)
    at org.springframework.test.context.support.AbstractTestContextBootstrapper.buildMergedContextConfiguration(
      ....


Process finished with exit code 255

2. The project layout

The project layout is as follows:

project-layout.xml
my-test-project
  +--pom.xml
  +--src
    +--main
      +--com
        +--example1
          +--Application.java
    +--test
      +--com
        +--example2
          +--TestAsync.java

The Application.java code is:

Application.java
package com.example1; //notice this package


import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;


@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

The test code is:

TestAsync.java
package com.example2; //notice this package name


import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.junit4.SpringRunner;


@RunWith(SpringRunner.class)
@SpringBootTest
public class TestAsync {
...
}
  • The @SpringBootApplication is in Application.java, which has a package named com.example1.
  • The test class is in the com.example2 package, which is neither the same as the @SpringBootApplication package nor a subpackage of it.

This image illustrates the package difference:

package_difference

3. The reason for the Unable to find @SpringBootConfiguration exception

The root cause of the Unable to find @SpringBootConfiguration exception is that the test class cannot locate the @SpringBootApplication class.

But why does this happen? Even though the @SpringBootApplication class exists, the test class cannot “see” it because of the specific mechanism used by @SpringBootTest to locate the @SpringBootApplication class. The mechanism works as follows:

package_find_mechanism

As shown in the image, the @SpringBootTest class searches for the @SpringBootApplication class starting from its own package (com.example2) and moves up to the root package (/). If it fails to find the @SpringBootApplication class, it throws the Unable to find @SpringBootConfiguration exception.

Here is the official description of this mechanism:

The search algorithm works up from the package that contains the test until it finds a @SpringBootApplication or @SpringBootConfiguration annotated class. As long as you’ve structured your code in a sensible way, your main configuration is usually found.

4. How to resolve this problem

There are three ways to resolve this exception:

  1. Move your test class to the com.example1 package, which is the same as the @SpringBootApplication class.
  2. Move your test class to a subpackage of com.example1, for example, com.example1.test.
  3. Use @SpringBootTest(classes = Application.class), where Application.class is the @SpringBootApplication class.

4.1 Way 1: Move the test class to the same package

solve_way_1

4.2 Way 2: Move the test class to a subpackage

solve_way_2

4.3 Way 3: Specify the @SpringBootApplication class explicitly

Modify the @SpringBootTest class as follows:

TestAsync.java
package com.example2;


import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.junit4.SpringRunner;
import com.example1.Application; //notice this line


@RunWith(SpringRunner.class)
@SpringBootTest(classes = Application.class) //notice this line
public class TestAsync {
...
}

Key changes:

  • Import the com.example1.Application class.
  • Add the classes parameter to the @SpringBootTest annotation to specify the @SpringBootApplication class explicitly.

After making these changes, rerun the test, and the exception should disappear.

5. Summary

The IllegalStateException: Unable to find @SpringBootConfiguration exception occurs when the test class cannot locate the @SpringBootApplication class due to package misalignment. To resolve this issue, ensure your test class is in the same package or a subpackage of the @SpringBootApplication class. Alternatively, you can explicitly specify the @SpringBootApplication class in the @SpringBootTest annotation. Proper package structure and configuration are key to avoiding this exception.

Final Words + More Resources

My intention with this article was to help others who might be considering solving such a problem. So I hope that’s been the case here. If you still have any questions, don’t hesitate to ask me by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Tags: