Actuators: Types, Operation, Selection, and Control

Spring Boot Actuator Mappings Endpoint

Learn how to use Spring Boot Actuator /actuator/mappings to inspect MVC, WebFlux, servlet, resource, and management routes and troubleshoot 404 and 405 errors.

The Spring Boot Actuator mappings endpoint lists request-handler mappings registered by a running application. It is useful when you need to determine which URLs, HTTP methods, controllers, functional routes, static resources, and management endpoints are actually active at runtime.

The endpoint describes the application that is running, not the API behavior that someone intended to implement. A route shown in a design document may be missing from the running application, while a route shown by Actuator may come from framework configuration or a dependency.

What the mappings endpoint does

Spring uses a HandlerMapping to associate an incoming HTTP request with a handler. A handler might be a controller method, a WebFlux handler function, a resource handler, a servlet, or an Actuator endpoint. The mappings endpoint reports these associations and the conditions that must be satisfied before a handler is selected.

The default URL is:

GET /actuator/mappings

Depending on the application, the response can help you verify:

• Whether a controller was detected during startup.
• Which path patterns are registered.
• Which HTTP methods each route accepts.
• Whether parameters, headers, or media types restrict a route.
• Which handler method and handler class process a request.
• Which WebFlux functional routes are present.
• Which static resource, servlet, welcome-page, view-controller, and management routes exist.

Endpoint location and availability

Spring Boot Actuator endpoints have two separate concepts: enabled and exposed. An endpoint can be enabled inside the application but not made available over HTTP. HTTP exposure is controlled independently from other technologies such as JMX.

In many production configurations, only a small set of endpoints is exposed. The mappings endpoint must therefore be explicitly included if it is not already exposed by the application policy.

Management base path

The default management base path is /actuator, so the default mappings URL is /actuator/mappings. If the base path changes, the endpoint moves with it. For example, with management.endpoints.web.base-path=/manage, the URL becomes /manage/mappings.

If Actuator uses a separate port, the host and port also change. With management.server.port=8081 and a base path of /manage, a local request is made to http://localhost:8081/manage/mappings.

Basic requests

curl http://localhost:8080/actuator/mappings

This unsecured form is suitable only for a deliberately unsecured local development setup. When Spring Security protects the endpoint, use an authorized client:

curl -u user:password http://localhost:8080/actuator/mappings

Enabling and exposing the endpoint

The following properties enable the endpoint and expose it over HTTP:

management.endpoints.web.exposure.include=health,info,mappings
management.endpoint.mappings.enabled=true

The equivalent YAML configuration is:

management:
  endpoints:
    web:
      exposure:
        include: health,info,mappings
  endpoint:
    mappings:
      enabled: true

A separate management server can isolate management traffic from application traffic:

management.server.port=8081
management.endpoints.web.base-path=/manage
management.endpoints.web.exposure.include=health,info,mappings

With this configuration, the mappings endpoint is served at /manage/mappings on port 8081.

Securing mappings output

Mappings output can reveal internal URL structures, controller and handler class names, endpoint technologies, administrative interfaces, and routes that were not intended to be public. Treat it as operational information.

• Expose it only to trusted users or internal networks.
• Prefer a separate management port when the deployment architecture supports it.
• Protect the endpoint with Spring Security authentication and authorization.
• Give access only to an operations role or another narrowly defined authority.
• Use a development or test profile for broad local exposure, and keep production exposure restricted or disabled.

Spring Security rules should distinguish management endpoints from ordinary application routes. The exact matcher and authority names depend on the security configuration, but the policy should require an authenticated principal with a specific management role for /actuator/mappings. A response of 401 generally indicates missing or invalid authentication; 403 generally indicates that authentication succeeded but authorization failed.

Understanding the response structure

The response is JSON grouped by application context and mapping type. Exact field names and categories vary across Spring Boot versions, dependencies, and configuration, so use the structure as diagnostic data rather than assuming every application produces identical JSON.

Common high-level sections include:

• Application context groups: Identify the context in which registrations exist. Applications with a parent context, child context, or management context may show more than one group.
• Dispatcher servlet mappings: Describe Spring MVC registrations, including annotated controller methods and other MVC handlers.
• Reactive handler mappings: Describe WebFlux annotated controllers, functional routes, and other reactive handlers.
• Actuator mappings: List management endpoint routes such as health, info, and mappings when they are enabled and exposed.
• Resource and servlet mappings: Show static resource handlers, servlet-specific registrations, welcome pages, view controllers, or custom handler mappings when present.

Within an individual mapping, look for metadata such as the path predicate or pattern, HTTP method, required parameters, headers, consumed media types, produced media types, handler method, and handler class.

Common mapping conditions

Content negotiation is the process of matching and selecting representations such as JSON. A route can have the expected path and method but still be ineligible because its consumes, produces, Content-Type, or Accept conditions do not match.

Spring MVC controller mappings

In Spring MVC, @RequestMapping declares general request conditions. @GetMapping and @PostMapping are composed annotations that specialize it for GET and POST requests. Other composed annotations include mappings for PUT, PATCH, and DELETE.

@RestController
@RequestMapping("/api/orders")
class OrderController {
  @GetMapping("/{id}")
  Order getOrder(@PathVariable Long id) { /* ... */ }
}

The class-level path and method-level path are composed into the effective route /api/orders/{id}. The mappings response should identify the GET condition and the OrderController.getOrder handler method, although the precise JSON nesting depends on the Spring Boot version.

Controller mappings can contain several conditions:

• Class and method paths: Spring combines a class-level prefix with a method-level suffix.
• HTTP methods: @GetMapping registers GET, while @PostMapping registers POST.
• Path variables: Segments such as {id} are captured and supplied to a handler parameter.
• Parameters: A mapping can require or exclude query parameters.
• Headers: A mapping can require a particular request header or header value.
• Consumes: The handler can restrict accepted request bodies to types such as application/json.
• Produces: The handler can restrict response representations to types such as application/json.

Spring WebFlux mappings

WebFlux supports annotated controllers with familiar annotations such as @RequestMapping and @GetMapping. These mappings appear in reactive handler-mapping sections and identify the controller method that handles a matching request.

WebFlux also supports functional routing through a RouterFunction. A RouterFunction is a routing definition that matches a request predicate to a handler function:

@Bean
RouterFunction<ServerResponse> productRoutes(ProductHandler handler) {
  return route(GET("/products/{id}"), handler::getById);
}

Functional routes can appear differently from annotated controller mappings. Instead of a controller class and method annotation, the response may show a reactive predicate containing the HTTP method and path and a reference to the handler function. Look for the route predicate and the referenced function or handler bean.

Additional mapping types

The response can contain more than REST controller routes. Depending on the web stack, dependencies, and configuration, it may include:

• Static resource handlers: Routes that serve files such as JavaScript, CSS, images, or other resources.
• Welcome-page mappings: Rules for serving a default index or welcome resource.
• View-controller mappings: Simple paths that forward to a view without a controller method.
• Servlet-specific mappings: Registrations belonging to a servlet or DispatcherServlet path.
• Custom HandlerMapping implementations: Application or library infrastructure that contributes its own request-selection rules.
• Management endpoint mappings: Actuator routes registered for the management web server.

Do not assume that a category present in one application will appear in another. Spring Boot version, MVC versus WebFlux, optional dependencies, custom beans, static resources, and management configuration all affect the result.

Practical route inspection

Inspect all registered mappings

1. Request /actuator/mappings with an authorized client.
2. Locate the relevant application context.
3. Open the dispatcher servlet section for MVC or a reactive handler section for WebFlux.
4. Search for a known API prefix such as /api/orders.
5. Compare the path, method, conditions, and handler details with the request you are testing.

Large responses are easier to inspect with a JSON processor. For example, after saving the response to mappings.json, search for an API prefix or handler name:

jq '.. | objects | select(tostring | contains("/api/orders"))' mappings.json

The exact JSON path differs by Spring Boot version, so recursive searches are often more practical than relying on a fixed response schema.

Verify an MVC controller

For the OrderController example, search for the effective path /api/orders/{id}, the GET method, and the handler method getOrder. If the class-level prefix is absent, the controller may not have been registered as expected. If the method-level suffix is absent, inspect the annotation or configuration that declares the method.

Inspect a WebFlux functional route

For the RouterFunction example, find a reactive mapping whose predicate includes GET and /products/{id}. Its handler representation may be a function reference instead of an annotated controller method. This difference is expected and helps identify which routing style registered the route.

Using mappings to troubleshoot routes

The endpoint is particularly useful for separating registration problems from request-shape problems. First determine whether a candidate mapping exists. Then compare every relevant condition with the actual request.

Diagnosing a 404

Suppose GET /api/customers returns 404 even though a controller class exists. Search the mappings response for the expected path and handler. If no entry exists, investigate component scanning, conditional bean registration, profile-specific configuration, and controller annotations. If an entry exists under a different prefix, inspect server.servlet.context-path, spring.mvc.servlet.path, and reverse-proxy path rewriting.

An application context path or servlet path can make the externally requested URL differ from the path shown inside a mapping. A proxy can add or remove another prefix. Always compare the complete client URL with every deployment layer.

Diagnosing a 405

A 405 Method Not Allowed response means that a path exists but does not accept the request method. For example, if the response shows PUT and PATCH mappings for /api/orders/{id} but the client sends POST, the client request is inconsistent with the registered route. Either use PUT or PATCH as intended, or add a POST mapping if that is the desired API contract.

Diagnosing media-type mismatches

A route can appear present while a JSON request fails because the request's Content-Type does not satisfy consumes, or because the requested response type does not satisfy produces. Compare the mapping conditions with the request's Content-Type and Accept headers.

Troubleshooting the mappings endpoint itself

GET /actuator/mappings returns 404

• Confirm that the Actuator dependency is present.
• Confirm the configured management base path and management port.
• Confirm that management.endpoint.mappings.enabled is true or not disabling the endpoint.
• Confirm that mappings is included in HTTP exposure.
• Check whether a reverse proxy changes the externally visible path.

The response is 401 or 403

• Authenticate with an authorized user or token.
• Review Spring Security request matchers for management URLs.
• Verify the required management role or authority.
• Confirm whether access is intentionally restricted to an internal network or management port.

The response is too large

• Save it to a file and filter it with jq.
• Search for the application API prefix, handler class, or HTTP method.
• Use it for targeted runtime diagnosis rather than as public API documentation.

Environment-specific configuration

Broad exposure can be convenient during local development and automated tests, but production should use a smaller exposure policy. One approach is to include mappings in a local profile and omit it from the production profile. Another is to expose it only on a separate management port protected by network controls and Spring Security.

Review the complete deployment path when testing: application route, servlet context path, servlet path, management base path, management port, load balancer, and reverse proxy. A correct mapping registration does not guarantee that every external URL prefix forwards to it correctly.

Exam-relevant notes

• The default mappings endpoint is /actuator/mappings.
• Enabling an Actuator endpoint and exposing it over HTTP are separate decisions.
• HandlerMapping connects an incoming request to a handler.
• @RequestMapping is the general annotation; @GetMapping and @PostMapping are composed method-specific annotations.
• Class-level and method-level paths are combined into an effective route.
• A 404 usually suggests that no eligible mapping was found; a 405 usually means the path exists but the HTTP method is not allowed.
• Path, method, parameters, headers, consumes, and produces conditions all participate in route selection.
• WebFlux can register both annotated controllers and functional RouterFunction routes.
• Mappings output can expose sensitive internal details and should be protected.

Related Actuator topics

• Spring Boot Actuator overview
• Actuator HTTP trace
• Actuator configuration properties
• Actuator environment endpoint