Failure reports
When the application cannot start, spring_boot_dart prints a report that says what is wrong and what to do, instead of a stack trace. It is Spring Boot's failure analysis.
Why
A missing bean, two beans of the same type, a typo in a property: these are the common reasons a start fails, and a stack trace of the container rarely makes them obvious. The report names the bean, the key or the file, and suggests the fix.
Example
A service needs a PaymentGateway, and none is declared:
***************************
APPLICATION FAILED TO START
***************************
Description:
Bean 'checkout' required a bean of type PaymentGateway that could not be found.
Action:
Declare a bean of that type (a @Component class or a @Bean method), check its @Profile / conditions, or make the injection point nullable.
What is explained
The built-in analysis looks at the error and at the causes it wraps, starting with the innermost:
| Failure | Description | Action |
|---|---|---|
| A missing bean | Bean 'x' required a bean of type T that could not be found (with the creation path) |
Declare one, check its @Profile or conditions, or make the injection point nullable |
| Several candidates | required a single bean of type T, but 2 were found with their names |
@Primary, a List<T>, or @Qualifier |
| A cycle | The dependencies of some of the beans form a cycle: a → b → a |
@Lazy() on one injection point, an ObjectProvider<T>, or a third bean |
| An unresolved placeholder | Could not resolve placeholder 'shop.url' |
Define it in a config file, on the command line or as a variable, or give it a default |
| A bean name defined twice | The bean 'x' ... could not be registered |
Rename one, or spring.main.allow-bean-definition-overriding=true |
| A missing config file | Config data resource '...' via location '...' does not exist |
Check the location, or prefix it with optional: |
| A missing config location | Config data location '...' does not exist |
The same |
| An invalid property name | Configuration property name 'x' is not valid with the invalid characters |
Kebab case, lower-case, starting with a letter |
| Invalid properties | Binding to target properties under 'shop' failed: with each key |
Update the configuration |
| Renamed properties | These properties have been renamed: with the new names |
Use the new names |
| A port in use (web starter) | Web server failed to start. Port 8080 was already in use. |
Stop the other process or change server.port |
Any other failure is logged as Application run failed with the error and its stack trace.
Your own analyzer
A library that fails in a predictable way (a database that cannot be reached, a missing licence key) can explain it:
class LicenceFailureAnalyzer implements FailureAnalyzer {
@override
FailureAnalysis? analyze(Object failure) => failure is MissingLicenceException
? FailureAnalysis(
'No licence key was found for ${failure.product}.',
'Set neon.licence.key, or start with the community profile.',
failure,
)
: null;
}
Register it as a bean (a starter puts it in its auto-configuration), or pass it to SpringApplication(failureAnalyzers: [...]). When the start fails:
- the analyzers of the constructor are asked first (they also work for failures before any bean exists);
- then the
FailureAnalyzerbeans, sorted by@Order(only when the context got far enough to create them); - then the built-in analysis.
The first non-null answer is reported. analyze receives the error as thrown; an error raised while a bean is created is often wrapped in a BeanCreationException, so walk the cause chain when needed.
analyzeFailure(error, analyzers: [...]) runs the same analysis by hand, to test an analyzer or report a failure the same way in a tool.
Where the report goes
| Setting | The report |
|---|---|
| default | Logged at ERROR under spring_boot_dart.diagnostics.LoggingFailureAnalysisReporter; other failures as Application run failed under spring_boot_dart.SpringApplication |
SpringApplication(out: (line) => ...) |
Given to the function: the report text, or Application run failed: <error> |
With spring_boot_starter_logging, the logging system stays installed until the failure is logged, so the report reaches the log file too. After the report, ApplicationFailedEvent has been published and the error is rethrown.
The condition evaluation report
To see why an auto-configured bean is there or not, start with --debug. The ConditionEvaluationReport (positive and negative matches) is logged at INFO after the refresh, or after a failed start. See Conditions.
In Spring (Java)
class LicenceFailureAnalyzer extends AbstractFailureAnalyzer<MissingLicenceException> {
protected FailureAnalysis analyze(Throwable root, MissingLicenceException ex) {
return new FailureAnalysis("No licence key...", "Set neon.licence.key...", ex);
}
}
// META-INF/spring.factories
Analyzers are beans or constructor arguments, not spring.factories entries.