Troubleshooting Guide

Solutions to common issues with Spring Boot AutoConfigure.

Enable Debug Mode

debug=true

This shows the condition evaluation report at startup.

Common Issues

Issue: Bean Not Found

Symptoms: NoSuchBeanDefinitionException

Solutions:

1. Check component scanning includes the package
2. Verify @Component or @Bean annotation
3. Check conditional annotations
4. Enable debug mode to see why bean wasn't created

Issue: Circular Dependency

Symptoms: BeanCurrentlyInCreationException

Solutions:

// Use @Lazy
@Bean
public ServiceA serviceA(@Lazy ServiceB serviceB) {
    return new ServiceA(serviceB);
}

// Or restructure dependencies

Issue: Property Not Resolved

Symptoms: Property value is null or default

Solutions:

1. Check property name (use dashed notation: my-property)
2. Verify property file location
3. Check active profile
4. Use @Value("${property:default}") with default

Issue: Multiple Beans of Same Type

Symptoms: NoUniqueBeanDefinitionException

Solutions:

// Mark one as @Primary
@Bean
@Primary
public DataSource primaryDataSource() { }

// Or use @Qualifier
@Autowired
@Qualifier("specific")
private DataSource dataSource;

Issue: Auto-Configuration Not Applied

Symptoms: Expected beans not created

Solutions:

1. Check META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
2. Verify conditions with debug mode
3. Check for exclusions
4. Verify classpath has required dependencies

Debugging Tools

View Condition Evaluation Report

@Component
public class ConditionReportPrinter 
        implements ApplicationListener<ContextRefreshedEvent> {
    
    @Override
    public void onApplicationEvent(ContextRefreshedEvent event) {
        ConditionEvaluationReport report = ConditionEvaluationReport.get(
            event.getApplicationContext().getBeanFactory()
        );
        
        report.getConditionAndOutcomesBySource()
            .forEach((source, outcomes) -> {
                System.out.println(source + ": " + outcomes.isFullMatch());
            });
    }
}

List All Beans

@Component
public class BeanLister implements ApplicationListener<ContextRefreshedEvent> {
    @Override
    public void onApplicationEvent(ContextRefreshedEvent event) {
        String[] beans = event.getApplicationContext().getBeanDefinitionNames();
        Arrays.stream(beans).sorted().forEach(System.out::println);
    }
}

Performance Issues

Slow Startup

Solutions:

1. Use spring.jpa.hibernate.ddl-auto=validate in production
2. Set spring.data.*.repositories.bootstrap-mode=deferred
3. Use @Lazy for expensive beans
4. Profile startup with -Dspring.jmx.enabled=true

Memory Issues

Solutions:

1. Tune connection pool sizes
2. Configure cache limits
3. Use appropriate JVM settings

See Also

• Configuration Basics
• Common Patterns
• Edge Cases