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

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:

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:

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