Conditional Wiring in Full: Ten Questions About @Conditional

In plain words: conditional wiring means "let the container decide, at startup, whether this object should be created at all." You do not scatter if (production) { ... } branches through your code — you stick one annotation on a configuration class or a @Bean method, and the container asks a few questions before building it: Is the class on the classpath? Does that bean exist? Is the switch property on? Did the user already configure one? All four must pass for the bean to get registered; fail any one and it simply does not exist. The hard part is this: when a condition fails there is no error at all — the object just quietly disappears. That makes the real skill of this chapter not syntax but "how do I find out why it never took effect".

That figure gives the panorama, but "order" is not something you absorb by looking — boxes ③ and ④ look so alike that most people remember them backwards. Here is the same path as boxes you can click through one at a time:

After this article you should be able to answer:

• In what order does condition evaluation ask its four questions, and which condition class answers each one?
• Why does @ConditionalOnBean silently work in an auto-configuration class but break on your own @Configuration?
• When a bean vanishes with no exception, what is the very first command you run and the keyword you search for?

Before syntax, let's answer a more fundamental question: why not just hard-code the configuration instead of inventing a whole "condition" mechanism? Because the same code often has to behave differently across environments and dependency combinations. Three scenarios nearly every backend engineer has met:

• Scenario one: H2 in development, MySQL in production. The team wants in-memory H2 for local tests and MySQL when deployed. A hard-coded datasource means maintaining two code paths; the ideal is "one codebase that uses H2 when it detects H2 on the classpath"
• Scenario two: optional dependencies must degrade gracefully. A module uses Redis for caching, but some edge services deploy without Redis. It should "use Redis if present, fall back to a local ConcurrentHashMap if not", rather than failing startup
• Scenario three: a starter provides a default while letting users replace it. Your starter should supply a default HttpClient, but if the consumer defines one of the same type, theirs must win

All three share a trait: whether to wire something depends on the runtime environment and dependencies, not on a constant in the code. Conditional wiring is Spring's standard answer — it moves the "if this, then that" decision from if statements into annotations, letting the container decide at startup.

And the first place "runtime dependencies" are decided is not an annotation at all, it is the pom. Tick it yourself and the mechanism becomes obvious: untick H2 and every bean that DataSourceAutoConfiguration guards with @ConditionalOnClass disappears in a batch, while the startup log does not change by a single character.

Every condition annotation ultimately reduces to one meta-annotation: @Conditional. It carries no logic itself; it only binds a condition class:

The real decision is made by the Condition interface — note it has a single method returning a boolean:

A plain Condition only answers "true or false", but Spring adds a finer design inside — ConfigurationCondition, which splits evaluation into two phases:

That paragraph answered "when may a condition speak". What about "what can it ask about"? ConditionContext exposes exactly five things, and each condition class is tied to one of them. This is not memorable from a list, so play a round: pick a condition class on the left, then the one thing it can query inside matches().

On top of @Conditional, Spring Boot wraps a whole set of ready-made conditions. They fall into two families by what they look at:

Conditions are not independent — they have temporal dependencies. The classic case is @ConditionalOnBean: for it to answer "is a bean of this type present?", that bean's BeanDefinition must already be registered. Get the order wrong and it sees "not yet", making an incorrect decision.

This yields a counter-intuitive conclusion: the same condition annotation, evaluated at a different position and time, can produce a different result. Spring Boot uses three mechanisms to keep ordering controllable:

• User first is the foundation of the whole design: because the DeferredImportSelector postpones auto-configuration until after user configuration, @ConditionalOnMissingBean gets to "step aside"
• before / after handles ordering among auto-configurations, declared in pairs and forbidden from forming cycles
• @AutoConfigureOrder is the absolute-number fallback, and the official guidance is to prefer the first two

"User first" turns into a literal six-step hand-off the moment @ConditionalOnMissingBean is involved. Watch frame ⑤: the default withdraws, and nothing at all gets printed.

Turn that trap into one side-by-side picture and the only thing a beginner has to carry away is "which door does this annotation belong behind":

One-line test: write @ConditionalOnBean / @ConditionalOnMissingBean only in auto-configuration classes and starters; when your own business configuration needs "wire it conditionally", use @Profile or @ConditionalOnProperty.

The criterion is easy to state; "in which beat does a bean actually vanish" is not. Spread it out as a single-step run: six lines on the left, and on the right the variables and the call stack as they change. Press step repeatedly and watch beat ⑤ — the one where beanDefinitionCount drops by one and the screen shows no exception whatsoever:

Once you understand the Condition interface, you can build your own condition annotation. The "only on a given weekday" example below is playful, but every detail it uses is production-grade:

Many people think @Profile is a separate mechanism, but it is just an official preset of conditional wiring. Its definition makes this obvious:

ProfileCondition does something plain: it reads spring.profiles.active / spring.profiles.default and checks whether the active profiles fall within the list declared on the annotation. So "switch beans by profile" and "switch beans by condition" are the same mechanism — @Profile is a special case of @Conditional. Understand that and you can hold both in one mental model instead of memorizing two unrelated rule sets.

The hardest part of conditional wiring is its silence — when a condition fails, the bean vanishes with no error. So debugging skill matters more than syntax. The first tool is still the condition evaluation report:

Each line tells you which condition class (the OnClassCondition etc. in parentheses) made the call:

That loop — read the report, find the one line, fix the cause — deserves its own walkthrough, because the real blocker for a beginner is not writing conditions but not knowing where to look once a bean disappears:

A route is not enough, though — you have to practise it on a real stack. This is the most common shape in production: the code did not change, only the machine did. Do not read the analysis; click the frame you believe is guilty:

This annotation is the easiest to misuse, and two pitfalls must be known up front:

• Pitfall one: it only sees beans that are already registered. @ConditionalOnBean inspects already registered BeanDefinitions, not beans that will appear later. So it is tightly coupled to "who registers first" — which is why Section 4 keeps stressing order. When using it between auto-configuration classes, always pair it with before / after
• Pitfall two: never do heavy work in a condition. matches is evaluated repeatedly (the same condition may be called many times in one startup) and it runs synchronously on the startup critical path. Querying a database, making a network call, or parsing a large file inside it will slow down or even hang startup. Conditions should be fast, pure, and side-effect free

The demo below turns condition evaluation into switchable knobs. Toggle "user-defined DataSource" and "spring-jdbc on the classpath" and watch the wiring result change — exactly how @ConditionalOnMissingBean and @ConditionalOnClass cooperate in real work:

Everything above has been prose. Run these five kernel labs in order, about 30 seconds each; they map onto the five threads of this chapter: first how a single condition decides, then the whole wiring chain, then what a condition actually inspects, then applying the rules back to your own starter, and finally the more basic question of how an object gets into the container at all.

The first lab interrogates four conditions separately. Click onclass first (is the dependency there), then onprop (is the switch on), then compare onbean against missing side by side — the former asks "does it exist", the latter "did you configure one yourself". This pair is the easiest to remember backwards:

The second lab puts those conditions back on the auto-configuration pipeline. Click through imports → filter → sort → apply → report and you will see at which station the candidate count drops hardest, and why the same annotation answers differently at different stages:

The third lab answers a more fundamental question: what does a condition actually judge? The answer is the BeanDefinition — the "recipe" the container writes down before ever building the object (a metadata object describing how this bean should be created, not the bean itself). Once you see that layer, you understand that conditional wiring intercepts "should we write this recipe", not "should we call the constructor":

The fourth lab applies the whole rule set to your own starter: register the list → bind properties → create the bean → switch it off. After the first three stations, be sure to click off and compare the two ways of turning it off — exclude versus a switch property:

The fifth lab asks the question that comes even earlier: conditions decide "may we write this recipe", but how many sources are there for a recipe in the first place? Click scan, bean, import, auto in turn and each one shows which phase writes the BeanDefinition into the registry. Then click miss — the "package was never scanned" scene, whose error wording is almost identical to "blocked by a condition", which is precisely the distinction the stack in Section 7 turns on:

Buttons are fine, but eventually you type the commands yourself. This console talks to the same in-browser kernel and every reply is computed there — boot builds the container and prints the wiring log, then flip the switches one by one:

Now it is your turn to act as the container. Flip the three switches on the left; the right shows the startup result and the exact verdict line from the --debug report. Read the defaults across all three cells first, then change one cell at a time — the fastest way to internalize conditional wiring:

A warm-up question, testing exactly the default-value trap flagged in Section 3:

Then a comprehensive question that ties Sections 4 and 8 together with the vs figure:

Every "error text" row below can be copied verbatim into a search engine — do not paraphrase, do not abbreviate. Conditional-wiring failures share one trait: most never appear as a red exception; they appear as "something is simply missing".

Goal: build a tiny app where a bean exists only when a switch is on, and confirm both paths with your own eyes in the --debug report. Four files total.

Step one, the only dependency needed is Boot itself (no database, no Redis):

Step two, the main class DemoApplication.java (at src/main/java/com/example/cond/DemoApplication.java):

Step three, the condition-gated configuration class FeatureConfig.java (same package as the main class):

Step four, the config file src/main/resources/application.yml:

Expected output of the two runs (compare against these key lines):

Step five, add --debug and run once more, then scroll the report at the top of the console to your own entry:

Report fragment (on run 1 — your class is a scanned ordinary configuration class, so it appears neither in the auto-configuration positive nor negative list; search by the property name directly instead):

Acceptance checklist: ① is featureRunner in the container prints false / true for the two values; ② you can explain why beanDefinitionCount differs by exactly 1; ③ you can locate the Negative matches: block in the --debug output and explain why any one line was rejected.

Goal: change one thing at a time and watch how condition behaviour shifts. Do each once and write the two log lines into your notes.

1. Change the annotation to @ConditionalOnProperty(prefix = "feature", name = "enabled", havingValue = "true", matchIfMissing = true), then delete the whole enabled line from the yml. You will observe: the bean still registers (containsBean returns true) — that is "absent counts as on". Compare with deleting the same line without matchIfMissing in Level 1 (false) and the default value is burned into memory.
2. Replace @ConditionalOnProperty with @ConditionalOnBean(String.class) and leave the yml alone. You will observe: the result now drifts with "is there a String bean in the container at this moment", and may even differ between your machine and a colleague's because of loading order — exactly what Section 4 and the vs figure describe.
3. Keep the Level 1 code but add a second @Configuration class next to DemoApplication that defines its own @Bean Runnable featureRunner(). You will observe: because order within one class is not guaranteed, you may get BeanDefinitionOverrideException (disallowed by default since Boot 2.1) or both beans may exist. The fix is moving the default into an auto-configuration class using @ConditionalOnMissingBean.

Hint: after item 3, re-run the missing argument of the Section 11 cond lab — the abstract rule lands immediately.

Build yourself a "feature toggle kit" that uses every mechanism in this chapter.

• A custom condition annotation @ConditionalOnDayOfWeek (see Section 5) supporting DayOfWeek[] value()
• Two configuration classes: wire WorkdayReporter Monday to Friday, WeekendReporter on the weekend, both implementing one interface Reporter
• One master switch: when report.enabled=false neither is wired (@ConditionalOnProperty with matchIfMissing = true)
• One test hook: let the property report.day-of-week fake "what day today is", so unit tests need not wait until Monday
• A main that prints which Reporter is active, plus the corresponding verdict line from the --debug report

Acceptance checklist: ① with one and the same jar, produce three outcomes via command-line arguments (workday / weekend / all off) without repackaging; ② report.day-of-week=MONDAY triggers the workday branch on any actual day; ③ you can state in one sentence "why the two Reporters never appear together" and point at the evidence line in the --debug report; ④ someone picking this up for the first time can operate the toggles from the application.yml comments alone, without reading code.