Auto-Configuration Internals: From spring.factories to AutoConfiguration.imports

The last two articles taught you to run something and to pry open the three-in-one annotation. This one answers the question that stalls beginners most: why does one added dependency hand me a DataSource, a transaction manager and a JSON converter? There is no magic here — just a plain assembly line: jars ship with a candidate list, Boot reads it at startup, asks each entry a few questions ("did you configure this already? do you have that class?"), and registers only the ones that pass. The article splits that line into four stages, then teaches one more skill: when something does not take effect, how to make Boot tell you why.

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

• Which file does the candidate list come from, and at which version did spring.factories become AutoConfiguration.imports?
• What must an auto-configuration class satisfy before it really takes effect, and where do I read the reason when it is skipped?
• What is the correct way to replace Boot's ObjectMapper, and why is the overriding switch the wrong tool?

You create a Spring Boot project and add a single dependency to pom.xml:

In application.yml you write only three or four lines of database connection info. You configure no DataSource, no EntityManagerFactory, no PlatformTransactionManager. Yet after startup all of these beans are sitting happily in the container — @Autowired a DataSource and it just works.

There is a question worth asking here: the Spring IoC container only builds what you tell it to build; it does not conjure a connection pool out of thin air. So who registered these beans?

The answer is auto-configuration. It is not magic: it is a set of configuration classes written into the jar ahead of time, which only take effect when their conditions are met. This article takes the whole pipeline apart — who reads which file, who evaluates the conditions, and who finally puts the beans into the container.

"One line of dependency, a roomful of beans" is best ticked through yourself. This generator follows the same rules as the lesson text: tick Data JPA alone and watch it drag in spring-orm, hibernate-core and spring-boot-starter-jdbc by itself; then stack the MySQL driver and H2 on top and notice what two drivers on one classpath produces — that is exactly the scene in the Section 13 sandbox and the trace at the end of Section 14. Finally add RabbitMQ, then untick it again: the second experiment below shows you which gate removed it.

Everything starts from that one @Import on @EnableAutoConfiguration from the previous article:

The class that does the work is AutoConfigurationImportSelector. Its skeleton looks roughly like this:

Expanding getAutoConfigurationEntry, a full load is this sequence:

1. getCandidateConfigurations() obtains all candidate auto-configuration classes (the list file inside the jars)
2. Duplicates are removed (several jars may declare the same class) and anything the user excluded via exclude / excludeName / spring.autoconfigure.exclude is dropped
3. AutoConfigurationImportFilter performs a fast preliminary filter (for example OnClassCondition reads the classpath directly and can eliminate a large batch of irrelevant classes, saving parsing cost)
4. The survivors go to ConfigurationClassParser one by one
5. During parsing, the @Conditional conditions on the class and its methods are evaluated by ConditionEvaluator
6. Passers are registered as BeanDefinitions; failures are recorded in the ConditionEvaluationReport
7. The container runs refresh(), instantiating real beans from those BeanDefinitions

The two gates are not built the same and cannot do the same things — here they are side by side:

Look at the last row of the right column: only the second gate leaves a "why" behind. That is why "why did it not apply" can only ever be answered from the --debug report and never from the candidate-list stage — classes removed by gate one do not even appear by name. Beginners read this as "the report is missing my class"; Section 13 meets the same trap again.

Where does the "candidate list" come from? There is a version watershed here. Before Spring Boot 2.7 it was spring.factories; 2.7 introduced the new style, and 3.0 removed the old mechanism entirely.

The old style looked like this — a comma-separated class list continued with backslashes:

The new style is cleaner, one class per line, with no key to declare:

With the pipeline understood, let's look at a real player. Spring Boot's own DataSourceAutoConfiguration (lightly trimmed) uses nearly every key annotation in the toolbox:

Annotation by annotation — this is how you should read auto-configuration source:

• @AutoConfiguration: the new marker. It is equivalent to @Configuration(proxyBeanMethods = false) but additionally gains ordering (before / after). Legacy auto-configuration used @Configuration; new code should standardize on this
• before = HibernateJpaAutoConfiguration.class: declares "I must run before the JPA auto-configuration". JPA needs a DataSource, so the wrong order makes JPA fail to find one — exactly the topic of Section 5
• @ConditionalOnClass({ DataSource.class, ... }): these classes must exist on the classpath. Without spring-jdbc the whole configuration class is skipped and there will be no DataSource in the container
• @ConditionalOnMissingBean(type = "io.r2dbc.spi.ConnectionFactory"): if the project uses reactive R2DBC, let R2DBC handle it and get out of the way
• @EnableConfigurationProperties(DataSourceProperties.class): binds spring.datasource.* into a Java object for the @Bean methods below
• @Import(...): imports finer-grained configuration. Auto-configuration is nested and layered: the outer class decides "should we configure a DataSource", the inner one decides "which connection pool"

Auto-configuration classes are not peers — they have dependencies. The classic pair: DataSourceAutoConfiguration must run before HibernateJpaAutoConfiguration. If JPA runs first and looks for a DataSource while none is registered yet, startup fails with "no DataSource found".

Spring Boot offers three ways to express order:

Those three layers are not parallel rules; they are a pipeline where each stage silences the ones below it. Click through it and pay attention to box 4 — it is the unglamorous alphabetical fallback that makes "the same pom behaves the same on every machine" true:

Auto-configuration decides "should I take effect" through conditional annotations. The table below collects the most common ones; the next article covers each in depth:

When auto-configuration "does not take effect", guessing is the worst move. Spring Boot ships a condition evaluation report that prints every auto-configuration class's decision and the reason. Enable it in one of three ways:

Once on, the console prints a report whose heart is two sections — "who took effect" and "who was skipped, and why":

Of the three ways to turn the report on, the first (--debug as a launch argument) is fine for one local glance. Real diagnosis needs one of the other two, because only those can vary per environment. Use the generator like this: tick logging first and turn on DEBUG for the auto-configuration package alone — far quieter than a blanket debug: true, and it does not drown the rest of the output; then add the datasource block, since those url / username / driver lines are the remedy for Section 8 and for the trace at the end of Section 14; finally add Profile to move both groups into a per-environment document and get the shape most teams actually keep: noisy in development, quiet in production.

Auto-configuration is a "fallback when you configured nothing", so what is the right way to take over? First, a bad example: some people turn on this switch to make their bean win —

Since Spring Boot 2.1 this defaults to false (overriding not allowed). Turning it on seems to "override everything", but it turns "who wins" into a question of registration order: whether the auto-configuration class or your class registers first is undetermined, so you may get your implementation or Boot's default — an extremely hard-to-reproduce latent bug.

The right approach uses the fact that auto-configuration steps aside on its own. Almost every auto-configuration class carries @ConditionalOnMissingBean:

Why does this work? The clue planted back in Section 2: AutoConfigurationImportSelector is a DeferredImportSelector, postponed until after all user configuration has been processed. So when the auto-configuration class evaluates @ConditionalOnMissingBean, your DataSource is already registered, the condition reports "already present", and auto-configuration steps aside. Deferred import is precisely the technical guarantee of "user first".

"Deferred import → you register first → it evaluates afterwards → it steps aside" is exactly this six-frame sequence:

Now the same thing as a stepped run. Six lines on the left, and on the right the two cells that decide everything: whether the container already holds a dataSource, and who is evaluating. Press step through beats 3 and 4 — the half-second of ordering between them is the entire technical content of "user first":

The demo below turns auto-configuration condition evaluation into switchable knobs. Toggle the three condition switches and watch, per auto-configuration bean, when it is created and when it is skipped wholesale:

Enough buttons — this article's central question ("did it apply, and if not why") has three direct answers on the command line: conditions prints the evaluation record, cond flips one condition by hand, and restart walks the whole assembly chain again.

Type them in this order; the contrast between steps 4 and 5 is exactly the contrast between the two gates in Section 2:

1. boot — build the container, read the wiring log
2. conditions — who is in, who is out, with the reason in brackets
3. cond jdbcOnClasspath false — pretend JDBC is not on the classpath
4. restart, then conditions again — is DataSourceAutoConfiguration still in the report at all?
5. cond userDataSource true — simulate you defining your own DataSource, then restart
6. lab autoconf filter versus lab autoconf report — how many the fast sieve removed, how many the report kept

Section 2 gave you the sequence in prose. The demo below turns it into something you can advance stage by stage — the autoconf scenario simulates the auto-configuration chain, and its five buttons map onto "list → filter → sort → apply → report":

• Where candidates come from (imports): sweep META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports across every jar on the classpath and merge the fully-qualified names into one big list. This stage only does IO and checks no condition, so the count looks alarming (the built-in list alone has 130+ entries)
• Condition filtering (filter): AutoConfigurationImportFilter takes a rough cut first. You watch a large batch of configuration classes get eliminated because classes are missing from the classpath — this is the "fast knife" of Section 7; it never parses annotations
• Sorting (sort): survivors go to AutoConfigurationSorter: resolve before/after dependencies first, then @AutoConfigureOrder, then alphabetical fallback. The order printed here is the order you will later read in the report
• Getting applied (apply): full condition evaluation per class; passers become BeanDefinitions, failures are written into the report
• The report (report): results rendered as Positive matches / Negative matches / Exclusions / Unconditional — byte for byte what --debug shows in your console

Every stage of that line can be overridden by hand. These three demos each train one thing, and the last one is the practical version of Section 10's decision.

The first drills condition annotations. In cond, the missing argument demonstrates the umbrella rule — the shop lends an umbrella only because the guest brought none (no bean of that type exists, so auto-configuration supplies one); switch to report to see each verdict in the same wording --debug uses. Walk all four conditions once and you will never need to guess "why isn't it active" again:

The second runs the pipeline backwards: write a starter yourself and traverse the whole chain end to end. starter's four arguments are meta (register the auto-configuration class in the list), props (bind prefixed properties with @ConfigurationProperties), bean (create it once conditions pass), off (disable via spring.xxx.enabled=false). After this, Section 8's "step aside" mechanism stops being abstract — it is something you wrote in four lines:

The third trains "when several places declare the same property, who wins". Auto-configuration leans heavily on properties to open and close features, so precedence is mandatory knowledge: command line > JNDI > system properties > application-{profile}.yml > application.yml > defaults. The prop scenario demonstrates the overriding live:

The fourth experiment stitches this article back onto the previous one with a single picture: there are four roads an object can take into the container, and beanin's auto mode is the one this article is about — no scanning involved, no package name consulted, only the list file inside the jar. Flip to scan right afterwards and you have seen both fates side by side, which is exactly what the contrast figure below is trying to say:

And keep this contrast picture in mind — last article's "bean not found" and this article's "auto-configuration not taking effect" are two faces of one coin: your classes enter through the scanning door, framework classes through the registration door. Use the wrong door and they simply never arrive:

By now you actually hold six wrenches, but they do not grip the same bolt: some delete candidates, some change a verdict, one only matters after registration is finished. Pair each wrench with the stage it acts on, and the next outage stops being a guessing game:

The --debug report is long, but only four cells matter. Watch this animation first — it shows how the report gets written, which is exactly why we call it a decision snapshot rather than a log — then switch scenarios on the left and let the right tell you which cell to read:

Every fragment below pastes straight into a search box:

That rule has one common exception: auto-configuration did apply, but it could not produce a usable bean. Then it does throw, and it puts its own authorship into the stack. Below is what a fresh project with spring-boot-starter-data-jpa and no application.yml looks like — do not read the analysis, just click the frame you think is guilty:

Goal: turn on --debug, read one real auto-configuration chain, and locate the origin of five beans inside the report.

pom.xml:

The main class (src/main/java/com/example/autolab/AutolabApplication.java, note the root package):

One line is enough in src/main/resources/application.properties:

Run mvn spring-boot:run. Expected key fragment of the startup log (ordering and exact entries vary slightly with dependencies):

Now play "find things" three times, quoting the exact line each time:

1. Search DispatcherServletAutoConfiguration in Positive matches and say who handed you the DispatcherServlet bean
2. Pick any three entries in Negative matches, copy the Condition class name from the brackets, and say which class is missing in each
3. Remove debug=true and start with the --debug argument instead; confirm the report is identical (and feel why Section 13 says the three enabling styles are interchangeable)

Checklist: ① you can explain Positive versus Negative matches without notes; ② for at least one negative entry you can state "adding which dependency would promote it"; ③ you can say why the line Exclusions: None. deserves a deliberate glance.

Each variant changes one thing:

1. Promote a negative entry: add spring-boot-starter-amqp and restart. You will observe RabbitAutoConfiguration moving from Negative matches into Positive matches — the most direct proof that conditions are driven by the classpath.
2. Watch the yielding mechanism live: create MyJsonConfig with a @Bean ObjectMapper (set any date format), then hit an endpoint returning an object. You will observe the @ConditionalOnMissingBean verdict for JacksonAutoConfiguration flip, and your formatting winning. That is option B of Section 10 executed for real.
3. Manufacture the bad pattern deliberately: on top of step 2, set spring.main.allow-bean-definition-overriding=true and name your bean objectMapper. You will observe the conflict warning vanish while which implementation lives depends on registration order — keep both logs side by side in your notes and you will never forget why this is wrong.
4. Silence one auto-configuration by property: put spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration in application.properties. You will observe it listed under Exclusions, and EmbeddedDataSourceConfiguration disappearing from Positive matches with it.

Build a minimal starter named greeting-spring-boot-starter and walk the entire chain of this article.

• Two Maven modules: greeting-spring-boot-starter (dependency aggregation only) and greeting-spring-boot-autoconfigure (the code)
• The auto-configuration class must carry @AutoConfiguration, @ConditionalOnClass(GreetingService.class) and @ConditionalOnMissingBean, plus @EnableConfigurationProperties(GreetingProperties.class) binding the prefix acme.greeting
• GreetingProperties has at least two fields: prefix (default [hello]) and enabled (default true); add @ConditionalOnProperty(prefix = "acme.greeting", name = "enabled", havingValue = "true", matchIfMissing = true) on the @Bean method
• Register the class in META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
• A separate demo project depends only on the starter, sets nothing about component scanning, injects GreetingService directly and exposes GET /greet

Checklist: ① the demo starts with zero configuration and /greet returns text carrying the default prefix; ② changing acme.greeting.prefix takes effect immediately; ③ setting acme.greeting.enabled=false makes startup fail with "required a bean of type GreetingService", and the Negative matches section of --debug names the property condition that blocked it; ④ remove the optional dependency and watch @ConditionalOnClass erase the whole configuration class; ⑤ your README draws the four stages "list → filter → sort → apply" and marks which stage each of your files participates in.