Maaz Zindani

Loading the index…

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

Swagger UI URL shows the Whitelabel Error Page in Spring Boot

ErrorWhitelabel Error Page

Short answer

The Whitelabel page means Spring found no handler for that address. For Swagger UI the usual reasons are a missing or wrong springdoc artifact for your Spring Boot line, leftover springfox code, or opening a URL that ignores the context path or a custom springdoc path. Fix the dependency, then open /swagger-ui.html.

  • Applies to Spring Boot 3.x, springdoc-openapi 2.x, Gradle 8.x and 9.x, Java 17 and 21
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Request the OpenAPI JSON. If it answers, springdoc is working and only the UI address is wrong; if it also fails, the dependency is the problem.

    curl -i http://localhost:8080/v3/api-docs
  2. 2Match what you see, then jump to its fix

    1. 1/v3/api-docs also returns the Whitelabel pageThe springdoc starter is missing, or it is the Spring Boot 2 artifactFix
    2. 2The dependency report or the grep below lists springfoxSpringfox is still on the classpathFix
    3. 3/v3/api-docs works under a prefix, or the app sets server.servlet.context-path or springdoc.swagger-ui.pathThe URL ignores the context path or a custom springdoc pathFix

What does the error look like?

  • Whitelabel Error Page
  • Whitelabel Error Page when opening /swagger-ui.html

Cause 1 of 3

The springdoc starter is missing, or it is the Spring Boot 2 artifact

1Check

Spring Boot 3 needs the starter artifacts. The older springdoc-openapi-ui artifact belongs to the Spring Boot 2 line (springdoc 1.x).

./gradlew dependencies --configuration runtimeClasspath | grep -i -E "springdoc|springfox"

2Fix

Replace the old artifact with the starter that matches your web stack. Use the webflux variant for WebFlux.

// build.gradle
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.10.0'

3Verify

Restart the app and request the JSON again.

curl -i http://localhost:8080/v3/api-docs

Confirmed by springdoc.org

Did this fix it?

Cause 2 of 3

Springfox is still on the classpath

1Check

springdoc-openapi and springfox are unrelated libraries. Mixing them, or leaving springfox code behind after a move, breaks the UI.

grep -rn "springfox" build.gradle src/

2Fix

Remove every springfox dependency and the code that configures it, then keep only the springdoc starter.

// delete lines like this from build.gradle
// implementation 'io.springfox:springfox-boot-starter:...'

3Verify

Rebuild and open the UI.

./gradlew bootRun

Confirmed by springdoc.org

Did this fix it?

Cause 3 of 3

The URL ignores the context path or a custom springdoc path

1Check

The UI is served at the context path plus /swagger-ui.html by default. Setting springdoc.swagger-ui.path moves it, which people do when static content at the root clashes with the UI.

grep -rn -E "context-path|swagger-ui.path" src/main/resources/

2Fix

Open the address that matches your settings, or set the path yourself.

# application.properties
server.servlet.context-path=/foo
springdoc.swagger-ui.path=/swagger-ui.html
# UI is then at http://localhost:8080/foo/swagger-ui.html

3Verify

Open the full address in the browser.

curl -I http://localhost:8080/foo/swagger-ui.html

Confirmed by springdoc.org

Did this fix it?

How do I stop it coming back?

  • Pick the springdoc starter that matches the Spring Boot major version and the web stack.
  • Remove old documentation libraries completely when migrating.
  • Write the real Swagger UI address in the project README.

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.