Spring Boot condition report: locate the missing auto-configuration decision

Last updated: 5 Oct 20264 min read

tutorial

A condition report records why auto-configuration matched or backed off; inspect the exact condition before adding another bean or excluding a module.

Read the decision chain

A receipt HTTP client is absent after deployment. The class might be missing, a required property might be false, or a user bean may have caused a conditional default to back off. The condition report shows positive and negative matches by configuration source. Find the failed condition for the expected auto-configuration class, then inspect the actual classpath and property value. Missing-bean defaults] and property opt-ins] cover the two common decisions.

Use a controlled diagnostic surface

Startup debug logging can print the report during local diagnosis. Actuator can expose a conditions endpoint when installed and enabled, but do not expose that endpoint on an unrestricted public management surface: it reveals class and configuration details. Capture only the relevant entry in an incident note. A missing bean error by itself does not prove that scanning failed; component scanning] and auto-configuration are different paths.

Compare before changing code

Run the same packaged artifact with the failing and healthy configuration, then compare the condition entry. Do not add an explicit bean solely to silence an exception until the reason for backoff is known. A targeted test should assert the intended bean is present when the opt-in property is true and absent when false. That proves the contract without depending on the entire text of a report, which can change across framework versions.

Implementation contract

Logger diagnosticLog = LoggerFactory.getLogger(ReceiptApplication.class);
ConditionEvaluationReport report =
    ConditionEvaluationReport.get(context.getBeanFactory());
report.getConditionAndOutcomesBySource().entrySet().stream()
    .filter(entry -> entry.getKey().contains("ReceiptClient"))
    .forEach(entry -> diagnosticLog.info(
        "{} -> {}", entry.getKey(), entry.getValue()));

Cost and verification

Report inspection is a diagnostic task, not a request path. Exposing it broadly increases information leakage; large reports can also be noisy without a named condition to inspect.

Common Mistakes

Do not infer a scan failure from every missing auto-configured bean.
Do not publish the conditions endpoint to anonymous clients.
Do not assert the full report text in a version-sensitive test.