Fail fast if management base path and an endpoint mapping are both '/' on the main server port

[FyiurAmron]

Impossible for me to say if this is a bug or a feature/documented change, hence the ticket. Facts:

• the config below worked fine before the patch from Actuator endpoints with no operations that use selectors are not accessible when mapped to / #35426 (e.g. SB actuator 3.2.1) - actually, it's been used for literal ages, since early 2.x versions
• after going to any version with Actuator endpoints with no operations that use selectors are not accessible when mapped to / #35426 fix, (e.g. SB actuator 3.2.2) - it suddenly breaks. The RestController is no longer accessible at all, app acts like it "disappeared", even though it is still listed in the mappings

test snippets:

@RestController
@RequestMapping("/api")
class TestController {

    @PostMapping("endpoint")
    fun endpoint(): HttpEntity<*> {
        return ResponseEntity.EMPTY
    }

}

management:
  endpoints.web:
    base-path: "/"
    path-mapping:
      health: "/"

results for 3.2.1:

GET -> 405
POST -> 200
PUT -> 405

results for 3.2.2:

GET -> 404
POST -> 405
PUT -> 405

Further details:

• The config shown doesn't throw any exception and never did.
• I also didn't notice any kind of warnings emitted with it (went through logs with DEBUG log level)
• Changing health from / to e.g. /foo "fixes" the behaviour (i.e. the endpoints start to work again)
• Changing base-path to anything else than / (e.g. /foo) in this case triggers: Ambiguous mapping. Cannot map 'Actuator root web endpoint' method Actuator root web endpoint to {GET [/foo], produces [application/vnd.spring-boot.actuator.v3+json || application/vnd.spring-boot.actuator.v2+json || application/json]}: There is already 'Actuator web endpoint 'health'' bean method

My take on it is:

• If this config (i.e. both base-path and at least one of the mappings equal to /) is deemed invalid, it should throw an exception during bean init for this particular case, like the case with non-/ base and / endpoint. However, the valid use case for this was hiding the "root" actuator endpoint AFAIK.
• If this config is deemed valid, the RestController should still work when that config is used.

---

With all honesty, I'd say this is a bug, mainly due to backwards-compatibility reasons. The code in question did work in previous patches in the same major/minor release (AFAIK both 3.2 and 3.1 are affected in this way), and a patch shouldn't introduce breaking changes that ain't backwards-compatible even if they are just fixing some abuses or corner cases (and the code shown isn't even really one of those I'd argue). If it would introduced purely with a minor increase and clearly documented, only the lack of exception thrown would be a problem here.

[wilkinsona]

Thanks for the report. Unfortunately, I don't think I understand the problem as currently described. Your snippet shows the use of @RestController which is separate from the Actuator endpoint infrastructure. Perhaps you meant @RestControllerEndpoint or perhaps you are saying that the Actuator and its health endpoint being mapped to / prevents access to a standard @RestController endpoint on /api? To help to remove this confusion, please provide a complete yet minimal sample that reproduces the problem. You can share it with us by pushing it to a separate repository on GitHub or by zipping it up and attaching it to this issue.

Also, please note that Spring Boot 3.2.x is no longer supported. Any sample that you share with us should use 3.3.7 or 3.4.1 to demonstrate the problem.

[FyiurAmron]

perhaps you are saying that the Actuator and its health endpoint being mapped to / prevents access to a standard @RestController endpoint on /api?

this, precisely.

To help to remove this confusion, please provide a complete yet minimal sample that reproduces the problem. You can share it with us by pushing it to a separate repository on GitHub or by zipping it up and attaching it to this issue.

Sure thing. Gimme a sec.

Also, please note that Spring Boot 3.2.x is no longer supported. Any sample that you share with us should use 3.3.7 or 3.4.1 to demonstrate the problem.

Sure, no problemo, as this problem also affects 3.4.1; basically, everything higher than 3.2.1 or 3.1.7 (including >=3.1.8+, >=3.2.2, >=3.3.0 and >= 3.4.0) is affected.

[FyiurAmron]

@wilkinsona

spring-boot-actuator-vs-restcontroller-problem-43885-main.zip

Here you go mate :) Ping me if anything else is missing, but I guess this is as MCVE as it gets :)

[wilkinsona]

Thank you.

The problem's occurring because there's a clash at the path level between the mappings for the health endpoint and the mapping for your @RestController:

2025-01-21T10:13:12.592Z TRACE 61191 --- [           main] s.w.s.m.m.a.RequestMappingHandlerMapping : 
	t.v.b.Controller:
	{POST [/api/endpoint]}: endpoint()
…
2025-01-21T10:13:12.732Z TRACE 61191 --- [           main] s.b.a.e.w.s.WebMvcEndpointHandlerMapping : Register "{GET [/**], produces [application/vnd.spring-boot.actuator.v3+json || application/vnd.spring-boot.actuator.v2+json || application/json]}" to java.lang.Object org.springframework.boot.actuate.endpoint.web.servlet.AbstractWebMvcEndpointHandlerMapping$OperationHandler.handle(jakarta.servlet.http.HttpServletRequest,java.util.Map<java.lang.String, java.lang.String>)
2025-01-21T10:13:12.733Z TRACE 61191 --- [           main] s.b.a.e.w.s.WebMvcEndpointHandlerMapping : Register "{GET [/ || ], produces [application/vnd.spring-boot.actuator.v3+json || application/vnd.spring-boot.actuator.v2+json || application/json]}" to java.lang.Object org.springframework.boot.actuate.endpoint.web.servlet.AbstractWebMvcEndpointHandlerMapping$OperationHandler.handle(jakarta.servlet.http.HttpServletRequest,java.util.Map<java.lang.String, java.lang.String>)

WebMvcEndpointHandlerMapping is called first by the dispatcher servlet. The path match combined with the HTTP method mismatch results in a HttpRequestMethodNotSupportedException being thrown and a 405 response. This doesn't occur in 3.2.1 because of a bug in how to Actuator created its mappings with the health endpoint being mapped to //** instead of /**. This causes the path match to be missed.

The combination of a patch match and a method mismatch is detected in handleNoMatch in RequestMappingInfoHandlerMapping from where the HttpRequestMethodNotSupportedException is thrown. We may be able to accommodate mappings for both POST [/api/endpoint] and GET [/**] by overriding handleNoMatch in AbstractWebMvcEndpointHandlerMapping and returning null. This would then give subsequent handler mappings an opportunity to provide a match. Spring Data REST's RepositoryRestHandlerMapping does exactly this, for similar reasons I would guess.

I'd like to discuss this with the rest of the team as web request matching is a complex area. I may well be overlooking a risk in overriding handleNoMatch to return null.

[wilkinsona]

We may be able to accommodate mappings for both POST [/api/endpoint] and GET [/**] by overriding handleNoMatch in AbstractWebMvcEndpointHandlerMapping and returning null

We discussed this today and concluded that it wasn't a good idea. Returning null would mean that a request to a path that maps to an Actuator endpoint with an HTTP method that isn't supported will respond with a 404 rather than the more helpful and more correct 405.

The root of the problem here is that there are multiple mappings capable of handling the path /api/endpoint. Those are the health endpoint's /** mapping and the REST controller's /api/endpoint mapping. There is also ambiguity within the Actuator itself if other endpoints are exposed as well as the health endpoint because the health endpoint's /** mapping will overlap with their mappings. With the current implementation using Spring MVC, this overlap will prevent access to a specific health component when its name clashes with an endpoint's ID. For example, if there's a health component called flyway and the flyway endpoint is exposed, the flyway health component would be hidden and only the endpoint would be accessible.

If we do anything here it will be to try to detect overlapping mappings and to fail fast at startup but will need to be careful not to fail to eagerly and make things unnecessarily brittle. To that end, @FyiurAmron, can you please describe what your end goal was when mapping actuator and health to /?