
# Startup checks

When the application starts, the starter checks every controller and every `@ControllerAdvice` bean. A mistake stops the start, with one message that lists every problem found.

## Why

A wrong mapping would otherwise show up only when a client calls it, maybe in production: a path variable that is never filled, a parameter nothing can bind, two methods for the same request. Checked at startup, the mistake is seen at once, in a test or on the developer's machine, and all mistakes are reported together rather than one per run.

## Example

```dart
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';

class BookFilter {
  String? author;
}

@RestController()
@RequestMapping('/api/books')
class BookController {
  // The parameter names {id}, but the path has {isbn}: two problems.
  @GetMapping('/{isbn}')
  String find(@PathVariable('id') String isbn) => isbn;

  // A class parameter without an annotation: nothing can fill it.
  @GetMapping('/search')
  String search(BookFilter filter) => '';
}

@RestController()
@RequestMapping('/api/orders')
class OrderController {
  @GetMapping()
  List<String> list() => [];

  // The same request as list().
  @GetMapping()
  List<String> all() => [];
}
```

The application does not start, and the log shows:

```text
Invalid controllers:
  - BookController.find: @PathVariable "id" is not in the path
  - BookController.find: the path variable {isbn} of "/api/books/{isbn}" has no @PathVariable parameter
  - BookController.search: parameter filter (BookFilter) needs @PathVariable, @RequestParam, @RequestHeader, @CookieValue or @RequestBody
  - Ambiguous mapping: OrderController.all and OrderController.list both map GET /api/orders
```

## What is checked

Each line of the list starts with the method, as `Class.method`. The checks and their messages:

| Mistake | Message |
|---|---|
| two mapping annotations on one method | `BookController.find has several mapping annotations; use one (@RequestMapping.of for other methods)` |
| a malformed path pattern | `BookController.find: <reason> in "<path>"`, such as `"**" and "{*name}" may only appear at the end of a pattern`, `Duplicate variable {isbn}`, `Unbalanced "{" in "{isbn"`, `Malformed variable {...}`, `Invalid regex in {...}`, `A {*name} needs a name` |
| a `produces` or `consumes` that is not a media type | `BookController.find: invalid produces "<value>": <reason>` (or `consumes`) |
| a parameter with two binding annotations | `BookController.find: parameter isbn has several roles` |
| a `@PathVariable` whose name is not in the path | `BookController.find: @PathVariable "id" is not in the path` |
| a `{variable}` of the path without a `@PathVariable` | `BookController.find: the path variable {isbn} of "/api/books/{isbn}" has no @PathVariable parameter` |
| a `@PathVariable`, `@RequestParam`, `@RequestHeader` or `@CookieValue` of a type that is not a simple value | `BookController.find: the @RequestParam parameter filter (Filter) is not a simple value; use a String, number, bool, enum, DateTime, Duration, Uri or a List of them` |
| a parameter without annotation that nothing can fill | `BookController.search: parameter filter (Filter) needs @PathVariable, @RequestParam, @RequestHeader, @CookieValue or @RequestBody` |
| two `@RequestBody` parameters | `BookController.create has more than one @RequestBody` |
| a method returning a `Future` of a stream | `BookController.changes returns a Future of a stream: return the EventStream / Stream directly` |
| `@CrossOrigin(allowCredentials: true)` with all origins | `BookController.find: @CrossOrigin(allowCredentials: true) needs origins or originPatterns (all origins, "*", cannot be allowed with credentials)` |
| `@CrossOrigin(allowPrivateNetwork: true)` with all origins | `BookController.find: @CrossOrigin(allowPrivateNetwork: true) needs origins or originPatterns (all origins, "*", cannot be allowed to a private network)` |
| an `@ExceptionHandler` parameter that is not the exception, the request, the response or the headers | `@ExceptionHandler ApiErrors.notFound: parameter extra must be the exception, the ServerHttpRequest, the ServerHttpResponse or the HttpHeaders` |
| an `@ExceptionHandler` without an exception type | `@ExceptionHandler ApiErrors.timeout: give the exception types (@ExceptionHandler([MyException])) or take the exception as a parameter` |
| two methods for the same request | `Ambiguous mapping: OrderController.all and OrderController.list both map GET /api/orders` |

Rules:

- **"The same request"** means the same HTTP method, the same pattern and the same conditions. Two methods that differ in `consumes`, `produces` or `headers` are not ambiguous: the request decides (`GET /api/orders produces [text/csv]` and `GET /api/orders` are two mappings).
- **Placeholders are resolved first.** A `${...}` in a path or media type is filled from the configuration, then checked.
- **Parameters a custom `HandlerMethodArgumentResolver` supports** are never reported: the resolver is asked first (see [WebMvcConfigurer](../web-mvc-configurer.md)).
- **A `Map` parameter** of `@RequestParam` or `@RequestHeader`, and an `HttpHeaders` one, are allowed: they are not simple values but take all values.
- **When the checks run.** After every singleton bean is created (`afterSingletonsInstantiated` of the `requestMappingHandlerMapping` bean), before the server starts. The problems are thrown as one `StateError`, which fails the start like any other startup error.
- **What is not checked here.** The JSON classes are checked by the generator at build time and by the `ObjectMapper` at run time; whether a service exists for a constructor parameter is checked by the container.

To see the mappings that passed, set `logging.level.spring.web.mvc=trace`: each is logged as `Mapped GET /api/books/{isbn} -> BookController.find`, after the count at debug level.

## In Spring (Java)

Spring checks fewer things at startup. An ambiguous mapping fails the start (`Ambiguous mapping. Cannot map 'orderController' method ...`). A path variable without a parameter, a parameter nothing can fill, or a wrong `@ExceptionHandler` fail only the requests that reach them, often with a 500.

## See also

- [@RequestMapping and @GetMapping](request-mapping.md)
- [@PathVariable](path-variable.md)
- [@ExceptionHandler](../errors/exception-handler.md)
- [CORS](../cors.md)
