Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Spring Boot fails to start with Springfox after the 2.6 upgrade

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

  • Applies to Spring Boot 2.6, Java 17, Gradle 8
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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"
  2. 2Match what you see, then jump to its fix

    1. 1The failure appeared right after raising Spring Boot to 2.6 or later; Actuator is not used.Path matching default changed to PathPatternParserFix
    2. 2The property is set and the application still fails to start, with spring-boot-starter-actuator present.Actuator and Springfox togetherFix

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-matcher

3Verify

The application starts and the documentation endpoint answers.

./gradlew bootRun

Confirmed by github.com

Did this fix it?

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 actuator

2Fix

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

Confirmed by springdoc.org

Did this fix it?

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:

Related fixes

Back 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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.