Diagnosing 404 or Failed to Load Errors in SpringDoc Swagger UI

Diagnosing 404 or Failed to Load Errors in Swagger UI

The Swagger UI page returns a 404 Not Found or fails to render when you navigate to /swagger-ui.html in a Spring Boot application that uses SpringDoc OpenAPI.

Quick Takeaway

If the UI cannot locate openapi.json or its static resources, the most common fixes are correcting the context path, adding the required dependency, or adjusting Spring Security rules.

Typical Causes (Diagnostic Table)

Root Cause	Observable Symptom
Incorrect context‑path configuration	404 when accessing /swagger-ui.html or /v3/api-docs
Missing springdoc‑openapi‑ui dependency	Static assets (CSS/JS) not served → UI blank or 404
Spring Security blocks /v3/api-docs/** or /swagger-ui/**	403 or 404 from security filter
Custom OpenAPI bean throws exception at startup	Application fails to start, UI never registers
Server URL mismatch in spec (proxy/gateway)	UI loads but shows wrong host or missing definitions

Step‑by‑Step Checks

1. Confirm the dependency is present.

   Open pom.xml (Maven) or build.gradle (Gradle) and verify the springdoc-openapi-ui artifact.

   
   
       org.springdoc
       springdoc-openapi-ui
       2.6.0
   
   

   Run the command mvn dependency:tree (or ./gradlew dependencies) from the project root to list all resolved dependencies. Required permission: read access to the build file; no special OS rights needed. If the springdoc-openapi-ui entry is absent, add it and re‑run mvn install (or ./gradlew build) before proceeding.

2. Verify the raw OpenAPI JSON is reachable.

   From a terminal on the same host, execute:

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

   Expected check: HTTP 200 status and a non‑empty response body. A 404 indicates the endpoint is not mapped; a 500 suggests a bean‑initialization error. If you receive 404, continue to the next check.

3. Inspect Spring Security configuration.

   Locate the class that extends WebSecurityConfigurerAdapter (or uses SecurityFilterChain bean). Ensure the following AntMatchers are not denied:

   http.authorizeRequests()
       .requestMatchersEndpointMatchers()
       .antMatchers("/v3/api-docs/**").permitAll()
       .antMatchers("/swagger-ui/**").permitAll()
       .anyRequest().authenticated();

   If the matcher is missing, add it. Required permission: edit access to the security configuration file. Risk: inadvertently opening other endpoints if the rule is too broad.

4. Check application startup logs for URL mapping.

   Search the log for lines containing “Mapped” or “Registered” and the paths /v3/api-docs or /swagger-ui. Example snippet:

   2026-10-10 01:55:23.456  INFO 12345 --- [           main] o.s.web.servlet.DispatcherServlet : Mapped URL path [/v3/api-docs] onto handler [public java.lang.Object org.springdoc.core.models.transformers.ModelResolver.get]

   If no mapping appears, the OpenAPI bean failed to initialize; investigate custom bean definitions.

5. Validate context‑path settings.

   SpringDoc uses the server’s context path by default. If you have overridden server.servlet.context-path in application.yml or application.properties, ensure the UI URL matches:

   server:
     servlet:
       context-path: /myapp
   

   Then access http://localhost:8080/myapp/swagger-ui.html. If the UI loads, the context path was the issue. If not, proceed.

6. Examine custom OpenAPI bean definitions.

   If you define a OpenAPI bean that throws an exception during startup, the UI will not register. Look for code similar to:

   @Bean
   public OpenAPI customOpenAPI() {
       return new OpenAPI()
           .addSecurityItem(new SecurityScheme()
               .name("Bearer")
               .type(SecurityScheme.Type.HTTP)
               .in(SecurityScheme.In.HEADER)
               .scheme("bearer")
               .bearerFormat("JWT"));
   }

   Any exception stack trace in the startup log points to the problem. Fix the bean or comment it out temporarily to confirm.

Fixes Tied to Findings

• Missing dependency → Add springdoc-openapi-ui dependency, rebuild, and redeploy.
• Context‑path mismatch → Align the UI URL with server.servlet.context-path or set springdoc.swagger-ui.url to the correct path.
• Security block → Add permitAll rules for /v3/api-docs/** and /swagger-ui/** in the security config.
• Custom bean failure → Refactor the bean or remove it; ensure all required OpenAPI components are provided.
• Server‑URL mismatch → Update the info.title or info.version fields, or set springdoc.swagger-ui.path to match the actual host.

Escalation Criteria

If after performing all checks the UI still returns 404 or remains blank:

• Confirm that the application is running the expected Spring Boot version (2.7.x or newer) – older versions may have different package structures.
• Check for external reverse proxies (NGINX, Apache) that may rewrite URLs; ensure they forward /v3/api-docs and /swagger-ui/** unchanged.
• Review any corporate firewall or proxy that could block static resource requests from the browser console.
• If the problem persists, capture the full HTTP response headers and the complete startup log, then open a ticket with the SpringDoc support channel, referencing the diagnostic table above.

Practical Verification

After applying a fix, repeat the curl -I http://localhost:8080/v3/api-docs command. A 200 response with a JSON body confirms the API definition is reachable. Then open the UI in a browser; the Swagger interface should render without “Failed to load resources” errors. If the UI loads but shows an empty definition, the JSON may be malformed – re‑inspect the bean output.

Limitations

SpringDoc generates the OpenAPI JSON at runtime; heavy use of generic types in controller method signatures can increase memory consumption during startup. In large applications, monitor heap usage and consider limiting generic collections if you encounter “Too many open files” errors.

Never expose Swagger UI in production unless you restrict access via IP whitelisting or basic authentication, as it discloses endpoint contracts and may leak sensitive data.

Diagram Labels

• Swagger UI endpoint
• openapi.json file
• SpringDoc configuration
• Security filter