Skip to content
javahacks.dev
Spring Boot

Spring Boot Conditions Report to Debug Auto Configuration

Use the Spring Boot conditions evaluation report and the Actuator conditions endpoint to find out why an auto configuration did or did not apply.

5 min read
Summarize in AI
Flat illustration of a start button surrounded by Spring Boot starters, with the Spring Boot, Spring Security, Gradle, Docker and Apache Maven logos.

When a feature does not appear, or a default appears you did not want, the question is which auto-configuration applied and why. Spring Boot answers it directly. This post uses Spring Boot 4.

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

or in application.properties:

properties
debug=true

This is not the same as setting the log level to DEBUG for the whole application. debug=true only turns on the core loggers, including the report. At the end of startup you see:

Text
============================
CONDITIONS EVALUATION REPORT
============================

Positive matches:
-----------------
   DataSourceAutoConfiguration matched:
      - @ConditionalOnClass found required classes 'javax.sql.DataSource' (OnClassCondition)

Negative matches:
-----------------
   MongoAutoConfiguration:
      Did not match:
         - @ConditionalOnClass did not find required class 'com.mongodb.client.MongoClient' (OnClassCondition)

Reading the four sections

SectionWhat it tells you
Positive matchesApplied, and which conditions held
Negative matchesNot applied, and the first condition that failed
ExclusionsTurned off by exclude or spring.autoconfigure.exclude
Unconditional classesAlways applied

Typical questions it answers

  • Why is there no DataSource? Search for DataSourceAutoConfiguration. If it matched, a bean is missing for another reason, as in failed to configure a DataSource.
  • Why did your own bean not replace the default? Look for OnBeanCondition in the default's entry. If it says a bean of that type was found, your bean is registered, and the question is whether two exist.
  • Why is Security locking everything? SecurityAutoConfiguration and SpringBootWebSecurityConfiguration appear under Positive matches whenever the starter is present.

Searching the output for a name is faster than reading it:

Shell
java -jar app.jar --debug 2>&1 | grep -A4 "JacksonAutoConfiguration"

The Actuator endpoint

With spring-boot-starter-actuator, expose the endpoint for a running instance:

properties
management.endpoints.web.exposure.include=conditions
Shell
curl localhost:8080/actuator/conditions | jq '.contexts[].negativeMatches | keys'

The same data comes back as JSON, so you can diff two environments. This is useful when the application behaves differently in production and the classpath is the suspect. The endpoint reveals your internal structure, so secure it, as described in Java security basics.

After you know the reason

If a class was missing, add the dependency or check its scope. If a bean already exists, remove one or qualify the injection, as in no unique bean. If an auto-configuration should not apply, exclude it. The overall mechanism is described in how auto-configuration works.

Worked case: why is my DataSource not configured

The most common reason to open this report is a bean that Boot should have created and did not. Say the application starts with Failed to configure a DataSource. Run with --debug and search the output for DataSourceAutoConfiguration under the negative matches. The line beneath it states the failed condition, usually @ConditionalOnClass did not find required class 'javax.sql.DataSource' or did not find required class 'org.h2.Driver', which means the driver jar is missing from the classpath. A second pattern is @ConditionalOnMissingBean (types: javax.sql.DataSource) found beans of type 'javax.sql.DataSource' myCustomSource: Boot backed off because you defined your own bean, which is the intended behavior and a frequent surprise to a team that forgot it had done so.

Read each negative match as a sentence. The condition name tells you what Boot looked for, and the text after it tells you what it found instead. Very few debugging sessions need more than that.

Reading the report in a container or on CI

On a server there is no terminal to scroll through, so write the report to a file once and read it there. Starting the jar with --debug > conditions.txt 2>&1 captures it, and a search for the class name is faster than paging. In Kubernetes, set the environment variable DEBUG=true on a single pod, read the log, and remove the variable again, because debug mode raises the log level for the framework packages, and the volume is large. Leave debug mode off by default in every environment, since it is a diagnostic and noisy output hides real problems.

The report versus the Actuator endpoint

The conditions endpoint returns the same data as JSON and is useful for a running instance that you cannot restart. Expose it deliberately with management.endpoints.web.exposure.include=conditions, and protect it, because it lists your classpath and your bean names, which is information an attacker enjoys. Pipe the JSON through jq to answer one question quickly:

Shell
curl -s localhost:8081/actuator/conditions | jq '.contexts[].negativeMatches | keys[] | select(test("Redis"))'

That prints the Redis-related auto-configurations that did not apply, and a second query on the same document shows the reason for one of them.

Using the report to choose what to exclude

The positive matches are as informative as the negative ones. A service that should be small may show positive matches for Security, a template engine and a message broker that nobody uses, all pulled by a starter in the dependency tree. That list is your shortlist for trimming dependencies or adding exclusions, as in excluding auto-configuration. Saving three unused auto-configurations can shorten startup by a noticeable amount on a small service, and removing the dependency that caused them also shrinks the jar and the attack surface.

Common messages and what they mean

Some phrases appear in nearly every report. @ConditionalOnClass did not find required class means a library is missing from the classpath, and adding the dependency flips the condition. @ConditionalOnMissingBean found bean means you defined your own, and the auto-configured one stepped aside. @ConditionalOnProperty with a property name means a switch is off, and the message shows the key and the value it expected. @ConditionalOnWebApplication did not find reactive web application classes means the type of application differs from what the configuration needs. Learning these four turns a long report into a short list of facts. When none of them explain the behavior, the next step is the source of the auto-configuration class, which is short and readable.

Reporting a bug with the report attached

If you suspect a Boot bug, attach the relevant part of the conditions report to the issue. Maintainers can see at a glance what your classpath contained and which conditions failed, and a report with a minimal reproducer is the fastest way to get an answer. Strip anything private, such as internal bean names, before posting.

Where this does not apply

The report covers auto-configuration and @Conditional classes only. For ordinary beans in your scanned packages, the Actuator beans endpoint lists what the context holds. The official description is the Spring Boot reference on auto-configuration, and the Actuator endpoints page lists the rest.

Also inDebugging
Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.