Spring Boot fails to start with Springfox after the 2.6 upgrade
Failed to start bean 'documentationPluginsBootstrapper'Short answer
Spring Boot 2.6 switched Spring MVC path matching from AntPathMatcher to PathPatternParser. Springfox expects the old matcher, so startup fails with documentationPluginsBootstrapper. Set spring.mvc.pathmatch.matching-strategy to ant-path-matcher. If Actuator is on the classpath, the property is not enough; move to springdoc.
Fix it fast
1Find out which cause you have
Check which Boot and Springfox versions are on the classpath, and whether Actuator is among them.
./gradlew dependencies --configuration runtimeClasspath | grep -iE "springfox|actuator|spring-boot-starter-web"2Match what you see, then jump to its fix
What does the error look like?
Failed to start bean 'documentationPluginsBootstrapper'application fails to start with Springfox after upgrading to Spring Boot 2.6
Cause 1 of 2
Path matching default changed to PathPatternParser
1Check
The Spring Boot 2.6 release notes say the default changed from AntPathMatcher to PathPatternParser for Spring MVC handler mappings.
grep -rn "pathmatch" src/main/resources/2Fix
Set the older matcher in your configuration, as the release notes describe.
# application.properties
spring.mvc.pathmatch.matching-strategy=ant-path-matcher
# application.yml
spring:
mvc:
pathmatch:
matching-strategy: ant-path-matcher3Verify
The application starts and the documentation endpoint answers.
./gradlew bootRunConfirmed by github.com
Cause 2 of 2
Actuator and Springfox together
1Check
The release notes warn that with Actuator and Springfox the application may fail to start, because Actuator endpoints also moved to PathPattern matching and that strategy cannot be changed by a property.
./gradlew dependencies --configuration runtimeClasspath | grep -i actuator2Fix
Replace Springfox with springdoc. Remove the Springfox and Swagger 2 dependencies, add springdoc-openapi-starter-webmvc-ui, and swap the annotations: @Api becomes @Tag, @ApiModel and @ApiModelProperty become @Schema, @ApiParam becomes @Parameter, @ApiIgnore becomes @Hidden. A single Docket bean goes away; use springdoc.packagesToScan and springdoc.pathsToMatch.
// build.gradle
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:<version from springdoc.org>'3Verify
The application starts and the UI loads at /swagger-ui.html, the default path.
curl -I http://localhost:8080/swagger-ui.htmlConfirmed by springdoc.org
How do I stop it coming back?
- Read the release notes of each Spring Boot minor version before upgrading.
- Prefer a documentation library the vendor still maintains for your Boot version.
- Run the application, not only the unit tests, in the upgrade pull request.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- Nuclear Home VideoA video-streaming Android app built from scratch, engineered for smooth playback.
Related fixes
Back end
A scanner flags jackson-databind: how to upgrade it in Gradle
jackson-databind vulnerability reported by a dependency scanner
Find where the old jackson-databind comes from, then raise it.
3 causes, each with a fixBack end
Gradle cannot resolve spring-boot-gradle-plugin after a Spring Boot 3 upgrade
Plugin [id: 'org.springframework.boot', version: '3.0.1'] was not found in any of the following sources
Spring Boot 3 needs Java 17 or newer and a recent Gradle, and its Gradle plugin is published on the Gradle Plugin Portal.
3 causes, each with a fixBack end
bootJar cannot find the main class of a Spring Boot project
Main class name has not been configured and it could not be resolved
The Spring Boot Gradle plugin looks in the main source set's output for a class with a public static void main method.
2 causes, each with a fixBack end
Spring Boot fails at startup with an error processing a condition on an auto-configuration
java.lang.IllegalStateException: Error processing condition on org.springframework.boot.autoconfigure.jdbc.JndiDataSourceAutoConfiguration
This message only says Spring Boot failed while evaluating an auto-configuration condition.
3 causes, each with a fixBack end
Swagger UI URL shows the Whitelabel Error Page in Spring Boot
Whitelabel Error Page when opening /swagger-ui.html
The Whitelabel page means Spring found no handler for that address.
3 causes, each with a fixBack end
Spring Boot will not start because port 8080 is already taken
Action: Identify and stop the process that's listening on port 8080 or configure this application to listen on another port.
Spring Boot listens on 8080 unless told otherwise, and only one process can own a port.
3 causes, each with a fix