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

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

About this issue

  • Original URL
  • State: closed
  • Created 2 years ago
  • Comments: 19 (9 by maintainers)

Commits related to this issue

Most upvoted comments

@philwebb @wilkinsona

I am also interested in this issue and have created a PR to address it. I would appreciate your feedback. 🙂

Yeah. So what I meant is, with the current config, with reordering of the marchers we can get it to work. But if we start failing such configurations the work around (with the reorder) probably won’t work either.

But I can completely appreciate that this is a very specific issue with me where I am tied down to the / endpoint for health check at the moment. I have no qualms with that.

BTW I actually figured it out by debugging spring cloud gateway for hours actually. I am embarrassed to admit how many hours. 😄 Then I checked the commit history on WebFluxEndpointHandlerMapping, then through to discussions I got here.

I’ve repurposed this issue, but I’d like some discussion with the team to make sure there aren’t unexpected side effects and to decide when we should do it.

So, I faced this issue in a rather different way. Hoping to add to the discussion. So I have an application that runs spring cloud gateway. It’s deployed with a custom helm chart, but because of some issues with the cloud environment (potentially a bug), the cloud provider doesn’t respect my custom health point configured on the helm. As a result I am forced to use their default health endpoint which is /.

After recently upgrading Spring Boot 3.3.7, the cloud gateway simply stopped matching all my predicates. Given my limited knowledge of reactive programming, it was difficult for me to figure this out. But this seems like the same issue.

The issue with our gateway setup was WebFluxEndpointHandlerMapping is (as before) being executed before RoutePredicateHandlerMapping. So effectively all my calls were being mapped to the health endpoint with all the route configurations on cloud gateway being completely ignored. I was simply being served 405s.

I am still working on a solution, which will either involve using a different port for hosting the management endpoints or as suggested here reordering the mapping order using a “BeanPostProcessor”.

I thought I’ll add this comment because it’s another failure mode. Also, I am also limited by my cloud setup to use the / endpoint as health check. (At least until that issue is fixed). Not sure if failing fast is the way to go, but a warning is certainly in order.

That aside, a question: should an actuator path mapping consume all the requests that are underneath it (via /**) before considering e.g. normal RestControllers? IMVHO, actuator should do matching after all the user-defined controllers are handled, not before - as explicit manual config should, as a rule, override implicit defaults?

We can’t easily do something like this with our current design since we let Spring MVC decide which mapping to invoke.

MVC’s decision can be influenced by changing the ordering of the handler mappings. At the moment the various AbstractWebMvcEndpointHandlerMapping sub-classes are ordered at -100. This results in them being called quite early and before the handler mapping that deals with @RequestMapping.

@FyiurAmron you can change this order using a BeanPostProcessor:

@Bean
static BeanPostProcessor actuatorEndpointMappingOrderer() {
	return new BeanPostProcessor() {
		@Override
		public Object postProcessAfterInitialization(Object bean, String beanName) throws BeansException {
			if (bean instanceof AbstractWebMvcEndpointHandlerMapping endpointHandlerMapping) {
				endpointHandlerMapping.setOrder(Ordered.LOWEST_PRECEDENCE - 2);
			}
			return bean;
		}
	};
}

This will order the Actuator endpoints towards the end, immediately before the mapping for static resource handling. Note that your mapping of Actuator and its health endpoint to / will inhibit access to static resources (or anything else that’s ordered after it). I’m not sure that this is something that we’d want to officially support as it’s really relying on an implementation detail of the MVC-based endpoint infrastructure, but it may be sufficient to meet your needs.

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.

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.