Swagger UI URL shows the Whitelabel Error Page in Spring Boot
Whitelabel Error PageShort 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.
Fix it fast
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-docs2Match what you see, then jump to its fix
- 1
/v3/api-docs also returns the Whitelabel pageThe springdoc starter is missing, or it is the Spring Boot 2 artifactFix - 2
The dependency report or the grep below lists springfoxSpringfox is still on the classpathFix - 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
- 1
What does the error look like?
Whitelabel Error PageWhitelabel 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-docsConfirmed by springdoc.org
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 bootRunConfirmed by springdoc.org
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.html3Verify
Open the full address in the browser.
curl -I http://localhost:8080/foo/swagger-ui.htmlConfirmed by springdoc.org
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:
- 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
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 fixBack end
Spring Boot cannot load the MySQL JDBC driver class
Cannot load driver class: com.mysql.jdbc.Driver
Spring Boot checks that the driver class you name can be loaded before it builds the connection pool.
3 causes, each with a fix