Introduction

When custom Spring Boot auto-configuration does not create beans, the problem is usually in registration or conditions, not in the @Bean method itself. The fastest way to debug it is to treat auto-configuration as a packaging feature, not as a variation of component scanning.

Auto-Configuration Is Not Component Scanning

This is the first thing to get clear. A class annotated with @Configuration or @AutoConfiguration is not automatically discovered just because it exists on the classpath. Spring Boot must be told to import it as auto-configuration.

A minimal auto-configuration class for a library might look like this:

1package com.example.demo.autoconfigure;
2
3import org.springframework.boot.autoconfigure.AutoConfiguration;
4import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
5import org.springframework.context.annotation.Bean;
6
7@AutoConfiguration
8public class DemoAutoConfiguration {
9
10    @Bean
11    @ConditionalOnMissingBean
12    public DemoService demoService() {
13        return new DemoService();
14    }
15}

If this class is never imported by Boot, demoService() will never run. That is true even if the method itself is perfect.

Register It the Right Way for Your Boot Version

Spring Boot 3 and Spring Boot 2 use different registration files.

For Spring Boot 3, add the fully qualified class name to:

META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

Example content:

com.example.demo.autoconfigure.DemoAutoConfiguration

For Spring Boot 2, use spring.factories instead:

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
com.example.demo.autoconfigure.DemoAutoConfiguration

Using the Boot 2 file format in a Boot 3 starter, or the other way around, is one of the most common reasons a custom starter appears to “not detect beans.”

Conditions Can Prevent Bean Creation by Design

Even if the configuration class is imported correctly, the bean can still be skipped because one of its conditions does not match.

Example:

1package com.example.demo.autoconfigure;
2
3import org.springframework.boot.autoconfigure.AutoConfiguration;
4import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
5import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
6import org.springframework.context.annotation.Bean;
7
8@AutoConfiguration
9@ConditionalOnClass(DemoClient.class)
10public class DemoClientAutoConfiguration {
11
12    @Bean
13    @ConditionalOnProperty(prefix = "demo.client", name = "enabled", havingValue = "true")
14    public DemoClient demoClient() {
15        return new DemoClient();
16    }
17}

This bean appears only when:

• 'DemoClient is on the classpath'
• 'demo.client.enabled=true exists in configuration'

If either condition fails, the bean is intentionally omitted. That is not a detection bug. It is the framework following your rules.

Put Auto-Configuration in the Right Module

Custom auto-configuration usually belongs in a starter or library module, not mixed into the main application package. A common structure is:

• 'demo-spring-boot-autoconfigure'
• 'demo-spring-boot-starter'
• consuming application

This matters because application packages are often discovered through scanning, while starter packages are meant to be imported explicitly by Boot’s auto-configuration mechanism.

If the consuming application does not have the auto-configuration artifact on its runtime classpath, nothing else matters. The beans cannot load from a module that is not present.

Use Boot’s Condition Report

Spring Boot already exposes the exact reason an auto-configuration did or did not match. Turn on debug output:

debug=true

Or run the app with:

./mvnw spring-boot:run -Dspring-boot.run.arguments=--debug

Then inspect the condition evaluation report. It shows:

• whether your auto-configuration class was considered at all
• which conditions matched
• which conditions failed

If Actuator is enabled, the conditions endpoint can also help:

/actuator/conditions

That is usually much faster than guessing or stepping through framework internals.

Let Applications Override Your Defaults

Good auto-configuration should provide defaults without trapping the consuming application. That is why @ConditionalOnMissingBean is so important.

1@Bean
2@ConditionalOnMissingBean
3public DemoService demoService() {
4    return new DemoService("default");
5}

Now the application can define its own DemoService bean and your starter will back off automatically. Without that condition, your starter may create conflicts that make debugging harder.

A Practical Debugging Checklist

When a custom auto-configuration does not seem to work, check these in order:

1. Is the starter or auto-configuration module on the runtime classpath
2. Is the configuration registered in the correct metadata file for the Boot version
3. Are any @ConditionalOn... rules preventing bean creation
4. Is the consuming app overriding the bean intentionally
5. Does the condition report show your class being evaluated

That sequence usually identifies the real cause quickly.

Common Pitfalls

• Assuming a starter class will be found through component scanning.
• Using spring.factories with a Boot version that expects AutoConfiguration.imports.
• Adding strict conditions and then forgetting the configuration values or classes they require.
• Packaging the starter incorrectly so the consuming application never loads it at runtime.
• Debugging the @Bean method before confirming that the auto-configuration class was imported at all.

Summary

• Custom auto-configuration must be registered explicitly; it is not ordinary component scanning.
• Spring Boot 2 and Spring Boot 3 use different metadata files for registration.
• Conditional annotations often explain missing beans more accurately than “detection” does.
• Keep auto-configuration in a starter-style module and verify it is on the runtime classpath.
• Use the condition report early, because it tells you exactly why a bean matched or did not match.