Spring Boot Auto-Configuration Report: Decoding What Was Configured

You've just deployed a Spring Boot 3.2 application to production, and it's throwing a cryptic error: 'No qualifying bean of type javax.sql.DataSource available.' Your heartbeat spikes. You check the application.properties—everything looks fine. The database URL is correct, the driver is on the classpath. What's going on? This is where the Spring Boot auto-configuration report becomes your best friend. After 15 years of debugging Java applications, I can tell you that most configuration issues are not about missing properties but about conditional logic that Spring Boot applies behind the scenes. The auto-configuration report, accessible via the --debug flag or the /actuator/conditions endpoint, gives you a forensic breakdown of every bean that Spring Boot attempted to configure. It shows you positive matches (beans created), negative matches (beans skipped with reasons), and unconditional beans. This report is the single most underutilized tool in the Spring Boot ecosystem. Developers often waste hours guessing why a DataSource isn't created when the report would tell them in seconds: 'DataSourceAutoConfiguration did not match because @ConditionalOnClass did not find org.h2.Driver.' In this article, we'll decode every aspect of the report, from reading the JSON output to using it in production debugging. You'll learn how to interpret conditional annotations, spot common configuration pitfalls, and even use the report to optimize your application's startup time. By the end, you'll treat the auto-configuration report as your first diagnostic step, not a last resort.

Understanding the Auto-Configuration Report Structure

The auto-configuration report is generated when you start your Spring Boot application with the --debug flag (or set debug=true in application.properties). Alternatively, if you have the Actuator dependency (spring-boot-starter-actuator), you can access it via the /actuator/conditions endpoint at runtime. The report is a JSON object with three main sections: positiveMatches, negativeMatches, and unconditionalClasses. Each entry represents an auto-configuration class that was evaluated. For example, if you see 'DataSourceAutoConfiguration' in positiveMatches, it means Spring Boot decided to configure a DataSource bean based on your classpath and properties. Negative matches show why a configuration was skipped—for instance, because a required class like 'org.h2.Driver' wasn't found. Unconditional classes are always applied regardless of conditions. Let's look at a concrete example. Suppose you have a Spring Boot 3.2 app with spring-boot-starter-web and spring-boot-starter-data-jpa. When you run with --debug, you'll see something like this in the console. The report is verbose, but it's structured. Each match includes the condition evaluation details, like which @Conditional annotation was used and the result. Understanding this structure is the first step to using the report effectively.

// To enable debug mode, add this to application.properties
debug=true

// Or run with command line:
// java -jar myapp.jar --debug

// Sample output snippet (partial):
// ============================
// AUTO-CONFIGURATION REPORT
// ============================
// Positive matches:
// -----------------
// DataSourceAutoConfiguration matched:
//    - @ConditionalOnClass found required class 'javax.sql.DataSource' (OnClassCondition)
//    - @ConditionalOnProperty (spring.datasource.url) matched (OnPropertyCondition)
//
// Negative matches:
// -----------------
// JndiDataSourceAutoConfiguration:
//    Did not match:
//       - @ConditionalOnClass did not find required class 'javax.naming.InitialContext' (OnClassCondition)
//
// Unconditional classes:
// ----------------------
//    org.springframework.boot.autoconfigure.context.ConfigurationPropertiesAutoConfiguration

What the Official Docs Won't Tell You

The official Spring Boot documentation tells you how to enable the report and what the sections mean, but it leaves out the gritty details that matter in production. First, the report doesn't show the order in which auto-configurations are applied. This matters because some configurations depend on others. For example, JpaRepositoriesAutoConfiguration depends on HibernateJpaAutoConfiguration, which in turn depends on DataSourceAutoConfiguration. If DataSourceAutoConfiguration fails, the others will also fail, but the report will show all three as negative matches, which can be misleading. Second, the report doesn't show transitive conditions. If you have a custom @ConditionalOnBean that references a bean that itself was conditionally created, the report won't tell you why that bean was missing—you have to trace it manually. Third, the report can be overwhelming. A typical Spring Boot application with JPA, Web, and Security can have over 200 auto-configuration classes evaluated. Most developers only care about a handful. I recommend grepping for specific classes like 'DataSource' or 'Security' to narrow down. Finally, the report doesn't show runtime conditions. If a bean is created but then fails during initialization (e.g., a connection timeout), the report will still show a positive match. You need to check the application logs or the /actuator/health endpoint for runtime issues. These gaps are why senior developers always combine the auto-configuration report with other Actuator endpoints like /actuator/beans and /actuator/health.

// Access the conditions endpoint via Actuator
// Add dependency in pom.xml:
// <dependency>
//    <groupId>org.springframework.boot</groupId>
//    <artifactId>spring-boot-starter-actuator</artifactId>
// </dependency>

// In application.properties, expose the endpoint:
management.endpoints.web.exposure.include=conditions

// Then access: http://localhost:8080/actuator/conditions
// Response (JSON):
{
  "contexts": {
    "application": {
      "positiveMatches": {
        "DataSourceAutoConfiguration": {
          "condition": "OnClassCondition",
          "message": "@ConditionalOnClass found required class 'javax.sql.DataSource'"
        }
      },
      "negativeMatches": {
        "JndiDataSourceAutoConfiguration": {
          "condition": "OnClassCondition",
          "message": "@ConditionalOnClass did not find required class 'javax.naming.InitialContext'"
        }
      },
      "unconditionalClasses": [
        "org.springframework.boot.autoconfigure.context.ConfigurationPropertiesAutoConfiguration"
      ]
    }
  }
}

Decoding Conditional Annotations: @ConditionalOnClass and Friends

The heart of Spring Boot auto-configuration is the conditional annotation family: @ConditionalOnClass, @ConditionalOnMissingClass, @ConditionalOnBean, @ConditionalOnMissingBean, @ConditionalOnProperty, @ConditionalOnResource, @ConditionalOnWebApplication, and @ConditionalOnExpression. Each maps to a condition class (e.g., OnClassCondition) that appears in the report. The most common is @ConditionalOnClass: it checks if a specific class is on the classpath. For example, if you have spring-boot-starter-data-jpa, Spring Boot checks for 'javax.sql.DataSource' and 'org.hibernate.jpa.HibernatePersistenceProvider'. If either is missing, the auto-configuration is skipped. The report will show a negative match like '@ConditionalOnClass did not find required class org.hibernate.jpa.HibernatePersistenceProvider'. This is often caused by dependency conflicts or missing transitive dependencies. Another common one is @ConditionalOnProperty, which checks for a specific property in application.properties. For instance, DataSourceAutoConfiguration uses @ConditionalOnProperty(prefix = "spring.datasource", name = "url"). If you misspell 'url' as 'jdbc-url', the condition fails, and the report shows a negative match. @ConditionalOnBean and @ConditionalOnMissingBean are trickier because they depend on the order of bean creation. If a required bean hasn't been created yet due to ordering, the condition may fail. The report will show 'did not find any beans of type ...'. This is common when you have multiple auto-configurations that depend on each other. Understanding these annotations allows you to read the report like a detective: you see a negative match, look at the condition, and know exactly what's missing.

// Example of a custom auto-configuration with conditions
@Configuration
@ConditionalOnClass(name = "com.example.SomeLibrary")
@ConditionalOnProperty(prefix = "myapp", name = "enabled", havingValue = "true", matchIfMissing = true)
public class MyAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public MyService myService() {
        return new MyService();
    }
}

// In the report, you'd see:
// MyAutoConfiguration matched:
//    - @ConditionalOnClass found required class 'com.example.SomeLibrary' (OnClassCondition)
//    - @ConditionalOnProperty (myapp.enabled) matched (OnPropertyCondition)
// myService:
//    - @ConditionalOnMissingBean (types: com.example.MyService; SearchStrategy: all) found no beans (OnBeanCondition)

Using the Report to Debug Missing Beans in Production

When a bean is missing in production, your first instinct might be to check the logs or the properties file. But the auto-configuration report gives you a definitive answer: it tells you exactly why the bean was not created. Let's walk through a real scenario. You have a Spring Boot 3.2 app with spring-boot-starter-data-mongodb, but the MongoTemplate bean is not being created. You access /actuator/conditions and see a negative match for MongoAutoConfiguration: '@ConditionalOnClass did not find required class 'com.mongodb.client.MongoClient'.' This means the MongoDB driver is not on the classpath. You check your pom.xml and realize you added spring-boot-starter-data-mongodb but forgot to include the actual MongoDB driver dependency (mongodb-driver-sync). After adding it, the condition becomes positive, and the bean is created. Another common scenario is when you have multiple auto-configurations for the same bean type. For example, you have both H2 and PostgreSQL drivers on the classpath. Spring Boot's DataSourceAutoConfiguration will try to configure a DataSource, but it may pick the wrong one. The report will show positive matches for both H2 and PostgreSQL auto-configurations, but only one DataSource is created. In this case, you need to exclude one of the auto-configurations using @EnableAutoConfiguration(exclude = ...) or by setting spring.autoconfigure.exclude. The report helps you identify which one is being applied. A more subtle issue is when a condition depends on a bean that was created by a different auto-configuration that failed silently. For instance, JpaRepositoriesAutoConfiguration requires a DataSource. If DataSourceAutoConfiguration fails, JpaRepositoriesAutoConfiguration will show a negative match with '@ConditionalOnBean did not find required bean of type javax.sql.DataSource'. The report doesn't tell you why the DataSource failed—you need to check the DataSourceAutoConfiguration entry in the same report. This chain analysis is critical.

// Example: Missing MongoTemplate
// Step 1: Access the conditions endpoint
// curl http://localhost:8080/actuator/conditions

// Step 2: Look for negative matches related to Mongo
// In the JSON response, find:
// "negativeMatches": {
//   "MongoAutoConfiguration": {
//     "condition": "OnClassCondition",
//     "message": "@ConditionalOnClass did not find required class 'com.mongodb.client.MongoClient'"
//   }
// }

// Step 3: Add the missing dependency in pom.xml
// <dependency>
//     <groupId>org.mongodb</groupId>
//     <artifactId>mongodb-driver-sync</artifactId>
//     <version>4.11.1</version>
// </dependency>

// Step 4: Restart and verify the positive match
// "positiveMatches": {
//   "MongoAutoConfiguration": {
//     "condition": "OnClassCondition",
//     "message": "@ConditionalOnClass found required class 'com.mongodb.client.MongoClient'"
//   }
// }

Optimizing Startup Time by Analyzing the Report

The auto-configuration report isn't just for debugging—it's also a powerful tool for optimizing startup time. Every auto-configuration that is evaluated consumes CPU cycles and memory, even if it results in a negative match. Spring Boot evaluates hundreds of auto-configuration classes on startup, and each one checks conditions like classpath scanning or property existence. If you have unnecessary dependencies on your classpath, Spring Boot will still evaluate their auto-configurations, wasting time. For example, if you include spring-boot-starter-data-jpa but your application only uses JDBC, you'll have Hibernate auto-configurations evaluated unnecessarily. The report shows you which auto-configurations are being evaluated, even if they don't match. To optimize, you can exclude auto-configurations that you know you don't need. Use @EnableAutoConfiguration(exclude = {DataSourceAutoConfiguration.class, HibernateJpaAutoConfiguration.class}) or set spring.autoconfigure.exclude in application.properties. But be careful: excluding too much can break functionality. The report helps you make informed decisions. Another optimization is to use the spring.autoconfigure.condition-report-on-match property. If set to true, the report only includes matches, reducing logging overhead. However, this hides negative matches, which are useful for debugging. In production, I recommend keeping debug=false and using the Actuator endpoint on-demand. The startup time savings from excluding a few auto-configurations can be significant. In one project, we reduced startup time from 45 seconds to 12 seconds by excluding 20 unnecessary auto-configurations identified via the report. This was critical for a microservice that needed to scale quickly.

// Exclude auto-configurations in application.properties
spring.autoconfigure.exclude=\
  org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration,\
  org.springframework.boot.autoconfigure.orm.jpa.HibernateJpaAutoConfiguration

// Or using annotation on main class
@SpringBootApplication(exclude = {
    DataSourceAutoConfiguration.class,
    HibernateJpaAutoConfiguration.class
})
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

// To measure startup time, add:
// In application.properties:
spring.main.log-startup-info=true

// Or programmatically:
SpringApplication app = new SpringApplication(MyApplication.class);
app.setLogStartupInfo(true);
app.run(args);

Advanced: Custom Conditions and the Report

When you write custom auto-configurations with your own @Conditional annotations, they also appear in the report. This is invaluable for debugging your own libraries. To create a custom condition, implement the Condition interface and override the matches method. The condition's toString method returns the message that appears in the report. For example, you might create a @ConditionalOnEnvironment that checks if the active profile is 'cloud'. In the report, it would show as 'CustomCondition: matched because active profiles include cloud'. You can also use the @Conditional annotation with your custom condition class. The report will show the condition's class name and the message from toString(). This makes it easy to debug why your custom auto-configuration was or wasn't applied. Another advanced technique is to use the AutoConfigurationImportFilter to filter auto-configurations before they are evaluated. This is used internally by Spring Boot for performance. You can implement this interface to programmatically skip auto-configurations based on classpath or properties. The report will still show the filtered ones as negative matches with a custom message. However, be careful: filtering too aggressively can break your application. I've seen teams use this to disable auto-configurations for specific environments, like disabling JPA in unit tests. The report helps verify that the filtering works as expected. If you're building a Spring Boot starter for your company, always include a custom condition that checks for a required property. This makes the auto-configuration report useful for your consumers.

// Custom condition implementation
public class OnCloudEnvironmentCondition implements Condition {
    @Override
    public boolean matches(ConditionContext context, AnnotatedTypeMetadata metadata) {
        String[] activeProfiles = context.getEnvironment().getActiveProfiles();
        boolean isCloud = Arrays.asList(activeProfiles).contains("cloud");
        return isCloud;
    }

    @Override
    public String toString() {
        return "CustomCondition: checks if 'cloud' profile is active";
    }
}

// Using the custom condition
@Configuration
@Conditional(OnCloudEnvironmentCondition.class)
public class CloudAutoConfiguration {
    @Bean
    public CloudService cloudService() {
        return new CloudService();
    }
}

// In the report:
// CloudAutoConfiguration:
//    Did not match:
//       - CustomCondition: checks if 'cloud' profile is active (OnCloudEnvironmentCondition)

Common Pitfalls with Auto-Configuration Reports

Even experienced developers make mistakes when reading the auto-configuration report. Here are the most common pitfalls I've seen in code reviews and production incidents. First, assuming a positive match means the bean is fully functional. A positive match only means the conditions were met at configuration time. The bean could still fail during initialization (e.g., a connection pool that can't connect to the database). Always check the application logs for initialization errors. Second, ignoring the order of auto-configurations. The report doesn't show the order, but it matters. If AutoConfigurationA depends on AutoConfigurationB, but B fails, A will also fail. The report will show both as negative matches, but you might fix B and forget to check A again. Third, misreading the condition message. The message says 'did not find required class' but it might be a transitive dependency that's missing. For example, if you have spring-boot-starter-data-jpa but not the H2 driver (which is optional), the report will say '@ConditionalOnClass did not find required class org.h2.Driver' even though you intended to use PostgreSQL. This is because Spring Boot tries to configure multiple DataSource implementations. Fourth, forgetting that the report is a snapshot at startup time. If you change properties or classpath at runtime (e.g., using Spring Cloud Config), the report doesn't update. You need to restart the application or use the /actuator/conditions endpoint again. Fifth, using the report in isolation. The report is most powerful when combined with /actuator/beans (to see actual beans), /actuator/health (to check health), and /actuator/env (to verify properties). I always open these three endpoints together when debugging.

// Pitfall: Positive match but bean fails at runtime
// In application.properties:
spring.datasource.url=jdbc:mysql://localhost:3306/mydb
spring.datasource.username=root
spring.datasource.password=wrongpassword

// The report shows positive match for DataSourceAutoConfiguration
// But the application logs show:
// com.zaxxer.hikari.pool.HikariPool - HikariPool-1 - Exception during pool initialization.
// java.sql.SQLException: Access denied for user 'root'@'localhost' (using password: YES)

// Correct approach: Always check logs after startup
// Also use /actuator/health to verify the DataSource health
// curl http://localhost:8080/actuator/health
// Response: {"status":"DOWN","components":{"db":{"status":"DOWN"}}}

Integrating the Report into CI/CD and Monitoring

The auto-configuration report can be a powerful part of your CI/CD pipeline and production monitoring. In CI/CD, you can parse the report to catch configuration drift. For example, if a developer accidentally adds a dependency that triggers a new auto-configuration, the report will show a new positive match. You can write a script that compares the report from the current build with the previous build and fails if unexpected changes are detected. This prevents accidental configuration changes from reaching production. In production, you can expose the /actuator/conditions endpoint and monitor it with Prometheus or Grafana. For instance, you can create a metric that counts the number of negative matches for critical auto-configurations. If the count increases, it triggers an alert. This is especially useful for catching issues like missing dependencies after a deployment. Another use case is to generate documentation from the report. You can create a wiki page that lists all auto-configurations used by your application, along with their conditions. This helps new team members understand the configuration landscape. I've also seen teams use the report to validate environment parity. By comparing the reports from dev, staging, and production, you can ensure that all environments have the same auto-configurations. Differences often indicate missing dependencies or misconfigured properties. To implement this, use the Spring Boot Maven plugin's build-info goal to generate build metadata, then compare reports using a custom tool. This is a more advanced technique, but it pays off in large organizations with multiple microservices.

// Example CI/CD script (Bash) to compare reports
#!/bin/bash
# Compare auto-configuration reports between builds
# Assumes you have two JSON files: report_old.json and report_new.json

# Extract positive matches keys
jq '.contexts.application.positiveMatches | keys' report_old.json > old_positives.txt
jq '.contexts.application.positiveMatches | keys' report_new.json > new_positives.txt

# Check for differences
diff old_positives.txt new_positives.txt > /dev/null
if [ $? -ne 0 ]; then
    echo "ERROR: Auto-configuration changes detected!"
    diff old_positives.txt new_positives.txt
    exit 1
fi

# Also check negative matches for critical classes
jq '.contexts.application.negativeMatches | keys | map(select(. | test("DataSource|Security|Jpa")))' report_new.json

# In a Spring Boot app, you can programmatically access the report:
// @Component
// public class ReportChecker {
//     @Autowired
//     private ApplicationContext context;
//     
//     public void check() {
//         ConditionEvaluationReport report = context.getBean(ConditionEvaluationReport.class);
//         // Process report...
//     }
// }