@SpringBootApplication: One Annotation, Three Meanings

Last article you got Hello World running, but you never actually pried open that one line @SpringBootApplication. This article does exactly that: split the single annotation into three responsibilities and make each boundary explicit. Why a whole article for it? Because the two most demoralising Boot errors — "bean not found" and "404" — are nine times out of ten not wrong business code but one of those three responsibilities failing to cover you. Once you know the boundaries, you hold a debugging map.

After this article you should be able to answer three questions:

• When a bean is missing, which annotation's scope failed to cover it, and how do I reverse-engineer that from the fully-qualified class name in the error?
• Once I set scanBasePackages, does the main class's own package still get scanned?
• What occasions call for exclude versus excludeName versus spring.autoconfigure.exclude?

You create a Spring Boot project, write a UserService annotated with @Service, inject it into a UserController, and startup fails outright:

The class is fine, the annotation is fine, it compiles — so why is the bean missing? Nine times out of ten the problem is not UserService at all, but the fact that the @SpringBootApplication on your main class never scanned the package it should have.

The best way to understand this is to pry apart that "three-in-one" annotation. In Spring Boot 3 it looks like this:

Strip the outer layer and @SpringBootConfiguration is surprisingly short:

The third sibling is the auto-configuration switch, and its definition is just as short:

That has a testable corollary: the ticket to auto-configuration is the classpath, not any switch. Every starter you tick hands a passport to a batch of auto-configuration classes; exclude can only turn away the ones that already got in — it cannot do anything about "the class is simply not there". So use the generator like this: tick Spring Web alone and note the single dependency in the output; add Data JPA plus the MySQL driver and count the new entries, then ask which of them is what lets Section 4's beans get past the condition check at all; finally tick Security — it is the one Section 8 is most often seen excluding, and the output shows you what it drags in.

Look again at the @ComponentScan inside @SpringBootApplication: it sets no basePackages at all. No value means the default, and the default is a single sentence:

The scan range is the package the main class lives in, plus all of its subpackages.

That sentence explains countless "bean not found" errors. The table below shows whether com.example.demo.service gets scanned, entirely depending on where the main class sits:

Placing the main class in the wrong spot is an extremely common and painfully hard-to-find mistake:

There are two fixes, and the first always wins:

@ComponentScan also supports excludeFilters, used to pick out classes that are scanned but should not be registered:

That animation shows the scope; the figure below shows the price — the same project with the main class moved down exactly one package:

"Downward only, never upward" sounds like common sense until the stack trace lands, and nobody remembers it then. Spread the mechanism over six stepped lines and let the right-hand pane refresh as you go: the base package in force, and who is on the candidate list. Press step repeatedly and watch beats 4 and 6 — the name that never appears is the whole story.

Since the rule is "its own package plus subpackages", the package layout and the main class location are bound by the same rule. The layout that causes the fewest surprises looks like this:

More auto-configuration is not automatically better. If you configured your own DataSource with @Bean, or pulled in a starter and do not want its security module just yet, you need to turn a few entries off. Three common approaches:

The first, written right on the main class, is compile-time checked:

The third packages that line into a single team-wide entry annotation:

The second tool earns its keep somewhere other than "one less line of code": it can answer per environment, which an annotation never can, because an annotation is frozen at compile time. Excluding the data-source auto-configuration in development and keeping it in production is a one-file change here and impossible there. Use the generator like this: tick Profile first and watch how spring.profiles.active plus the --- document separator moves the two lines above into an environment-specific block; then add the datasource block and think about who wins when an exclusion list and connection settings appear together; finally add logging, because logging.level is the setting you will touch most often while diagnosing auto-configuration.

Now back to the question from Section 1: why does @SpringBootApplication(scanBasePackages = "x") work at all, when scanBasePackages clearly belongs to @ComponentScan?

The answer is the @AliasFor meta-annotation. It does two things: declare aliases and forward across annotations. Here is how @SpringBootApplication uses it:

Because of it, Spring Boot can collapse "three annotations" into one from the user's point of view. Interviews love to ask whether @SpringBootApplication really is three annotations; answering "yes, and it forwards attributes down through @AliasFor" earns you the point.

That forwarding takes six frames from the name you type to a scan range that really moved:

@SpringBootApplication carries four @AliasFor declarations, plus one more inside @SpringBootConfiguration — six names to keep straight, which nobody memorises from prose. Play a round instead: the left column is the attribute you write on the main class, the right column is the annotation and attribute it actually changes. A wrong pair explains itself on the spot, and the last two pairs are where people usually slip.

Placing the main class correctly is enough inside one module, but multi-module setups trip people up. A typical scene:

The order module tries to inject UserService from user-module and gets "bean not found" at startup. The root cause is the same scan rule: order's main class is in com.example.order, so it only scans downward into com.example.order.*, while UserService is in com.example.user — siblings that can never see each other.

Two fixes, pick by team convention:

The configuration classes imported by @EnableAutoConfiguration do not take effect unconditionally. The demo below visualizes condition evaluation: every auto-configuration class is interrogated condition by condition and kept only if it passes. Try turning off the classpath condition and watch the auto-configuration be skipped wholesale:

Step back one question first: how many doors does an object have into the container? Section 4 was about "can the scan reach it"; this one is about "how many roads exist at all". The beanin scenario lays all four side by side — component scanning, @Bean methods, @Import, and whatever auto-configuration registers for you. Its final mode, "when it is not found", reproduces Section 1's required a bean that could not be found verbatim, and you can watch that it is never about an annotation failing — just a package that was never opened.

Enough buttons — type at it instead. This console talks to the same in-browser Java kernel and computes every reply live, which is exactly what this article's question needs: beans counts who got in, conditions asks why the rest did not, di shows who is waiting on whom.

Walk it in this order and step 4 is where a name goes missing:

1. boot — build the container and read the wiring log
2. beans — is your userService on that list?
3. lab triple scan — keep only the scanning layer and see who is left
4. lab beanin miss — reproduce the not-found scene directly
5. conditions — which condition let or blocked each auto-configuration class
6. di — the injection graph, so you can point at the broken edge

So far we described what it is made of. The demo below lets you switch each layer off and see what each one owns — the triple scenario simulates the assembly of @SpringBootApplication, and its four buttons are four ways to take it apart:

• @SpringBootConfiguration (config): keep only "this is a configuration class". The @Bean methods on your main class still register, while @Service classes and auto-configuration do nothing — this layer only answers "may this card define workstations"
• @ComponentScan (scan): add scanning. Your own UserService / HelloController now arrive, but there is no DispatcherServlet and none of the embedded-Tomcat beans — proof that "scanning yours" and "wiring the framework" are separate jobs
• @EnableAutoConfiguration (auto): add auto-configuration. A flood of framework beans lands and beanDefinitionCount jumps from a dozen to dozens — the answer to last article's "why does it run with nothing configured"
• All three together (all): the full @SpringBootApplication, plus a demonstration of how the four @AliasFor entries forward scanBasePackages / exclude inward

Four modes clicked through, now stack them in your head — this is the door-card analogy from the opening, one box at a time. Each box says plainly who it let in and who it turned away:

Knowing "three annotations" is not enough; you need to know at which moment each takes effect. Do these three demos in order and you cover the whole chain:

The first returns to the timeline from article #16. In bootrun you can see @SpringBootApplication being read during "prepare the context" and "post-process the context", while bean instantiation happens later inside refresh(). Annotations decide the roster, not the moment objects are built — a distinction many beginners blur:

The second interrogates condition annotations one by one. @ConditionalOnMissingBean — the umbrella rule: the shop lends one only because you did not bring your own — plus its evaluation timing and outcome are printed line by line in cond; switch to report to see the passed / failed grouping, formatted exactly like the --debug report in article #18:

The third resolves the "sibling modules cannot scan each other" problem from Section 8 using option three. The starter scenario shows a depended-on module shipping its own AutoConfiguration.imports: whoever depends on it gets the beans automatically, regardless of package names, with no reliance on scan ranges at all:

Start with this animation — it turns Section 4's prose into a chain you can recite: how a class annotated @Service becomes an object you can actually @Autowired. Nine out of ten "bean not found" errors happen between step 2 and step 3:

Pick a "surely fine" way to write it on the left; the right hands back the startup result and the exact line to change:

Every fragment below can be pasted verbatim into a search box:

Row two of that table is this article's home game, and here it is as a real stack. Do not read the analysis — click the frame you think is guilty. The difficulty of this one is that no frame in the stack points at the cause; the answer lives in two fully-qualified names inside the message text.

Goal: build a minimal project with "main class in the root plus layered subpackages", then deliberately break and repair "bean not found" three times.

pom.xml (one starter is enough):

Three files, watch the package levels (src/main/java/com/example/scanlab/):

Run mvn spring-boot:run. Expected startup log (the three key lines):

curl http://localhost:8080/greet returns hello from scanned package.

Now break it three times on purpose, watching one symptom each time:

1. Move ScanlabApplication to com.example.scanlab.web → startup fails immediately, Description: naming Greeter
2. Put it back in the root but add scanBasePackages = "com.example.scanlab.controller" → still failing, again missing Greeter (controller in, service out)
3. Keep step 2 and extend the list to {"com.example.scanlab.controller", "com.example.scanlab.service"} → works, but you are now hand-maintaining a scan list — feel why Section 8 calls that debt

Checklist: ① you can say which bean was missing in attempts one and two and why; ② you saved the exact error text of all three; ③ the final state is "main class in the root, no properties written".

Each variant changes one thing; write down what you observed:

1. Name collision: add com.example.scanlab.v1.UserController and com.example.scanlab.v2.UserController, neither named. You will observe ConflictingBeanDefinitionException printing both fully-qualified names. Then name one @RestController("v2UserController") and you will observe startup recovering.
2. excludeFilters: undo the explicit name and instead use @SpringBootApplication(excludeFilters = @ComponentScan.Filter(type = FilterType.ASSIGNABLE_TYPE, classes = V1UserController.class)). You will observe v1 pushed out without touching any class; try FilterType.REGEX on a whole package next.
3. exclude an auto-configuration: add exclude = HttpEncodingAutoConfiguration.class and request /greet. You will observe it appear under Exclusions (use --debug) and notice the charset change on non-ASCII responses — the live version of the sandbox's fourth cell.
4. Uniqueness: change one ordinary @Configuration class to also carry @SpringBootConfiguration, then run an empty @SpringBootTest. You will observe Found multiple @SpringBootConfiguration — the error points at the test while the cause sits in business code.

Build a two-module project multi-scan: a parent pom aggregating common-module and app-module, with the main class in app-module. Implement all three ways of letting app use common's beans, and document the comparison.

• Option A: shared ancestor package (both under com.example.xxx, main class at com.example)
• Option B: scanBasePackages listing both module packages explicitly
• Option C: common-module ships META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports registering its own configuration (formally introduced next article), with no scan configuration on the app side

Checklist: ① all three start and serve the same endpoint; ② your README states, per option, "what must change when a new module appears"; ③ deliberately omit one package in option B, paste the error, and explain why B is riskier than A/C; ④ in option C, find your own auto-configuration's positive-match entry with --debug.