A developer moved the @SpringBootApplication class into a sub-package and now several @SpringBootTest tests fail at startup. Diagnose why and give the fixes.

principalnice to knowfreq 35%

answer

Search goes UP only, never down/sideways
Main class must be ancestor of every test package
'Unable to find a @SpringBootConfiguration' error
@ComponentScan base = main class's package too
Fix: root package > classes= > test @SpringBootConfiguration

basics

~20 s

Detection only searches upward from the test's package. If the main class now sits in a sibling sub-package (not an ancestor of the tests), the search reaches the root without finding @SpringBootConfiguration and fails with 'Unable to find a @SpringBootConfiguration'. Fix: restore the root-package layout or set classes explicitly.

solid answer

~50 s

@SpringBootConfiguration detection walks from the test class's package upward toward the root, never sideways or downward. Moving @SpringBootApplication from com.myapp into, say, com.myapp.boot means tests under com.myapp.web no longer have it as an ancestor — the upward walk from com.myapp.web passes through com.myapp and the root without ever entering com.myapp.boot, so nothing is found and the context fails with Unable to find a @SpringBootConfiguration, you need to use @ContextConfiguration or @SpringBootTest(classes=...) with your test. Fixes, best to worst: (1) put the main class back in the root package so it's an ancestor of all tests — the canonical layout; (2) if it must live deeper, pin each test with @SpringBootTest(classes = Application.class) or add a package-level @ContextConfiguration; (3) provide a small @SpringBootConfiguration in the test source root. Also verify component scanning still covers your packages, since @ComponentScan's base package defaults to the main class's package.

`@SpringBootConfiguration` detection walks from the test class's package **upward** toward the root, never sideways or downward. Moving `@SpringBootApplication` from `com.myapp` into, say, `com.myapp.boot` means tests under `com.myapp.web` no longer have it as an ancestor — the upward walk from `com.myapp.web` passes through `com.myapp` and the root without ever entering `com.myapp.boot`, so nothing is found and the context fails with `Unable to find a @SpringBootConfiguration, you need to use @ContextConfiguration or @SpringBootTest(classes=...) with your test`. Fixes, best to worst: (1) put the main class back in the root package so it's an ancestor of all tests — the canonical layout; (2) if it must live deeper, pin each test with `@SpringBootTest(classes = Application.class)` or add a package-level `@ContextConfiguration`; (3) provide a small `@SpringBootConfiguration` in the test source root. Also verify component scanning still covers your packages, since `@ComponentScan`'s base package defaults to the main class's package.

code

java · 15 lines

java

// BROKEN: main class buried in a sub-package
package com.myapp.boot;            // was com.myapp
@SpringBootApplication
public class Application { }

// Test in a sibling sub-package can't find it (upward walk misses com.myapp.boot)
package com.myapp.web;
@SpringBootTest
class OrderControllerTest { }       // -> IllegalStateException at startup

// FIX 1 (preferred): move Application back to root package com.myapp

// FIX 2: pin the config explicitly
@SpringBootTest(classes = com.myapp.boot.Application.class)
class OrderControllerTestFixed { }

go deeper

for a junior

Recognize the 'Unable to find a @SpringBootConfiguration' error means the test can't locate the main class.

for a middle

Explain the upward-only search and the root-package fix.

for a senior

Also connect it to @ComponentScan base-package defaulting and choose among the fixes.

for a principal

Treat package topology as convention-API; enforce layout, weigh explicit-config trade-offs and context-cache impact at scale.

Root cause

The finder (AnnotatedClassFinder/SpringBootConfigurationFinder) implements a strictly upward search: from the test's package it checks that package, then each successive parent package, up to the root. It does not descend into sub-packages and does not scan siblings. So the @SpringBootConfiguration (your @SpringBootApplication) must reside in a package that is an ancestor of (or equal to) every test's package. Relocating it into a sub-package breaks that ancestor relationship for tests that aren't themselves under that sub-package.

Symptom

Context startup fails before any test body runs: java.lang.IllegalStateException: Unable to find a @SpringBootConfiguration, you need to use @ContextConfiguration or @SpringBootTest(classes=...) with your test.

Secondary effect: component scanning

@SpringBootApplication's @ComponentScan defaults its base package to the package of the annotated class. Even production wiring can break: moving the class into com.myapp.boot narrows scanning to com.myapp.boot.**, so beans in com.myapp.web/com.myapp.service are no longer scanned. That's a second, independent reason the move is harmful — the fix (restore root package) addresses both.

Fixes ranked

Restore the root-package convention. Main class in com.myapp; all code + tests beneath it. Zero annotations needed; both detection and scanning just work. This is the idiomatic Spring Boot layout and the right long-term answer.
Explicit classes. @SpringBootTest(classes = Application.class) (or a shared base test class carrying it) bypasses detection. Verbose and easy to forget on new tests.
@ContextConfiguration/package-info or a dedicated test @SpringBootConfiguration in the test source tree — anchors detection for tests without touching prod, but risks divergence from the real config.
If the deeper location is deliberate (e.g. multi-module), keep an explicit @ComponentScan(basePackages = "com.myapp") and @SpringBootConfiguration placement that still covers the intended packages.

The multiple-config sibling case

The inverse failure: two @SpringBootConfiguration classes reachable in the upward path (e.g. a stray test @SpringBootApplication) makes detection ambiguous and also fails. Same remediation: keep exactly one primary, or specify classes.

Principal-level framing

The deeper lesson is that package topology is API for Spring Boot's conventions. Refactors that move the main class or reshape packages silently change both test discovery and production component scanning. Codify the root-package layout, and prefer a single shared test base (or classes) only when a module genuinely lacks a reachable main class — while watching context-cache fragmentation from ad-hoc per-test configs.

### Root cause The finder (`AnnotatedClassFinder`/`SpringBootConfigurationFinder`) implements a **strictly upward** search: from the test's package it checks that package, then each successive **parent** package, up to the root. It does **not** descend into sub-packages and does **not** scan siblings. So the `@SpringBootConfiguration` (your `@SpringBootApplication`) must reside in a package that is an **ancestor of (or equal to)** every test's package. Relocating it into a sub-package breaks that ancestor relationship for tests that aren't themselves under that sub-package. ### Symptom Context startup fails before any test body runs: `java.lang.IllegalStateException: Unable to find a @SpringBootConfiguration, you need to use @ContextConfiguration or @SpringBootTest(classes=...) with your test`. ### Secondary effect: component scanning `@SpringBootApplication`'s `@ComponentScan` defaults its base package to the **package of the annotated class**. Even production wiring can break: moving the class into `com.myapp.boot` narrows scanning to `com.myapp.boot.**`, so beans in `com.myapp.web`/`com.myapp.service` are no longer scanned. That's a second, independent reason the move is harmful — the fix (restore root package) addresses both. ### Fixes ranked 1. **Restore the root-package convention.** Main class in `com.myapp`; all code + tests beneath it. Zero annotations needed; both detection and scanning just work. This is the idiomatic Spring Boot layout and the right long-term answer. 2. **Explicit `classes`.** `@SpringBootTest(classes = Application.class)` (or a shared base test class carrying it) bypasses detection. Verbose and easy to forget on new tests. 3. **`@ContextConfiguration`/package-info** or a dedicated test `@SpringBootConfiguration` in the test source tree — anchors detection for tests without touching prod, but risks divergence from the real config. 4. If the deeper location is deliberate (e.g. multi-module), keep an explicit `@ComponentScan(basePackages = "com.myapp")` and `@SpringBootConfiguration` placement that still covers the intended packages. ### The multiple-config sibling case The inverse failure: two `@SpringBootConfiguration` classes reachable in the upward path (e.g. a stray test `@SpringBootApplication`) makes detection **ambiguous** and also fails. Same remediation: keep exactly one primary, or specify `classes`. ### Principal-level framing The deeper lesson is that package topology is API for Spring Boot's conventions. Refactors that move the main class or reshape packages silently change both test discovery and production component scanning. Codify the root-package layout, and prefer a single shared test base (or `classes`) only when a module genuinely lacks a reachable main class — while watching context-cache fragmentation from ad-hoc per-test configs.

Besides test detection, what else breaks when the @SpringBootApplication class moves into a sub-package?
Component scanning. @SpringBootApplication's @ComponentScan defaults its base package to the annotated class's package, so moving it narrows scanning to that sub-package and beans in sibling packages stop being discovered at runtime — a production bug, not just a test one. Restoring the root package or setting explicit basePackages fixes both.
How would you enforce the root-package convention across a large codebase?
Keep exactly one @SpringBootApplication in the root package and code-review/architecture-test against strays; optionally an ArchUnit rule asserting the main class's package is a prefix of all others. For modules lacking a main class, standardize a shared @SpringBootTest base with explicit classes to avoid per-test drift and context-cache fragmentation.

saying these in an interview costs you the question

Thinking detection scans sub-packages downward, so any location works
Assuming the failure is a classpath/dependency issue rather than package topology
Overlooking that @ComponentScan's base package also shifts with the main class
Adding classes= to one test and assuming it fixes all the others

A developer moved the @SpringBootApplication class into a sub-package and now several @SpringBootTest tests fail at startup. Diagnose why and give the fixes.

§ answer

basics

solid answer

code

§ go deeper

▾level notes4 levels

▾deep dive~2 min

Root cause

Symptom

Secondary effect: component scanning

Fixes ranked

The multiple-config sibling case

Principal-level framing

▾common follow-ups2 questions

▾red flags4 flags

§ context

▾related questions3 questions

▾related topics3 topics

Root cause

Symptom

Secondary effect: component scanning

Fixes ranked

The multiple-config sibling case

Principal-level framing

answer

go deeper

context