
# 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:

```text
***************************
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:

```dart
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:

1. the analyzers of the constructor are asked first (they also work for failures before any bean exists);
2. then the `FailureAnalyzer` beans, sorted by `@Order` (only when the context got far enough to create them);
3. 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](conditions.md#the-condition-evaluation-report).

## In Spring (Java)

```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.

## See also

- [SpringApplication](spring-application.md)
- [Conditions](conditions.md)
- [Events](events.md)
