A team's custom FailureAnalyzer is never invoked — the app still prints a raw stack trace. What are the likely causes, and how do analyzer ordering and null returns factor in?

## Debugging checklist for "my analyzer never runs" ### 1. Wrong registration file (the #1 mistake) Spring Boot 2.7/3.x introduced `META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` — but **only** for auto-configuration classes. `FailureAnalyzer` registration was **not** migrated; it still lives in **`META-INF/spring.factories`**: ```properties org.springframework.boot.diagnostics.FailureAnalyzer=\ com.example.MyFailureAnalyzer ``` Symptoms of getting this wrong: the analyzer compiles, tests of the class pass, but at runtime it's simply never discovered. Also check the key spelling exactly — a typo in the fully-qualified key silently disables discovery. ### 2. Declared as a bean If someone slapped `@Component`/`@Bean` on it (perhaps to get injection), it won't be used for diagnostics — analyzers are loaded by `SpringFactoriesLoader`, not the context. Remove the stereotype and register in `spring.factories`. ### 3. Generic type points at the wrong throwable `AbstractFailureAnalyzer<T>` scans the cause chain for a throwable assignable to `T`. If the real cause is `MyException` but you wrote `AbstractFailureAnalyzer<IllegalStateException>` or targeted a wrapper, matching behavior won't be what you intend. Target the **most specific** exception you control. ### 4. analyze() returns null Returning `null` is a legitimate "not mine" signal, but an over-eager guard clause can make the analyzer decline the very case it was written for. Confirm the path that should produce a `FailureAnalysis` actually does. ### 5. Ordering and first-match-wins The diagnostics runner asks each analyzer in turn and stops at the **first non-null** `FailureAnalysis`. Analyzer order follows `SpringFactoriesLoader` order, adjustable with `@Order` / `Ordered` (lower value = higher priority). If a broad built-in analyzer (say, one matching a wrapper exception higher in the chain) returns first, your more specific message never appears. Give your analyzer higher precedence with `@Order(Ordered.HIGHEST_PRECEDENCE)` if it must win. ### 6. The exception isn't a startup failure at all Diagnostics only runs on the `SpringApplication` startup-failure path. If your exception is thrown while handling a request (post-startup), no analyzer runs — you'd use `@ControllerAdvice`/`@ExceptionHandler` for that instead. ### 7. It's masked by a different reporter or the exception is swallowed If the code catches your exception and recovers (so refresh succeeds), there's no fatal failure to analyze. Ensure the exception actually propagates out of context refresh. ## Design guidance for library authors When shipping a starter, bundle analyzers for the misconfigurations your users will hit, type them precisely, keep `analyze()` pure, write a message with a genuinely actionable Action, and register them in the starter's own `spring.factories`. Unit-test each analyzer by constructing the exception and asserting on description/action — that catches null-return regressions. ## Summary of the two mechanisms to keep straight - **Auto-configuration** → `META-INF/spring/...AutoConfiguration.imports`. - **FailureAnalyzer** → `META-INF/spring.factories`, key `org.springframework.boot.diagnostics.FailureAnalyzer`.