Introduction

If you call withDetail(...) in a custom Spring Boot health indicator but /actuator/health still shows only UP or DOWN, the problem is usually not the indicator itself. In most cases, the details were added correctly, but Actuator is configured not to expose them to the current caller.

What withDetail Actually Does

A custom indicator can attach extra information to the Health object it returns.

1import org.springframework.boot.actuate.health.Health;
2import org.springframework.boot.actuate.health.HealthIndicator;
3import org.springframework.stereotype.Component;
4
5@Component
6public class DatabasePingHealthIndicator implements HealthIndicator {
7    @Override
8    public Health health() {
9        return Health.up()
10                .withDetail("database", "reachable")
11                .withDetail("latencyMs", 12)
12                .build();
13    }
14}

That code does create health details. The missing piece is whether the actuator endpoint is allowed to show them.

Actuator Hides Details by Default

Spring Boot does this for security reasons. A health endpoint visible to load balancers or anonymous users should not automatically reveal internal system details.

The main property is:

management.endpoint.health.show-details=always

Other common values are:

• 'never'
• 'when-authorized'
• 'always'

If the property is never, or if it is when-authorized and the request is not authenticated with the required role, your custom details will stay hidden even though withDetail(...) worked.

Expose the Endpoint and Authorize It Correctly

You also need the endpoint to be exposed.

management.endpoints.web.exposure.include=health,info
management.endpoint.health.show-details=when-authorized
management.endpoint.health.roles=ACTUATOR

With that setup, only authorized users with the configured role see the detail payload.

If you are using Spring Security, your security config must also allow the request pattern you expect.

Health Groups Can Change What You See

Another source of confusion is health groups. If you call /actuator/health/readiness or another grouped endpoint, the response may differ from the root /actuator/health endpoint depending on which indicators are included in that group.

So if your custom indicator is not showing up where you expect, check:

• which endpoint URL you are calling
• whether the indicator belongs to that health group
• whether group-specific config overrides the default behavior

Verify the Indicator Is Actually Registered

If the endpoint shows no custom component at all, make sure Spring created the bean. A simple @Component on the health indicator is usually enough, but package scanning, conditional config, or profile restrictions can still prevent registration.

One quick test is to look for the indicator's contribution in logs or call the actuator endpoint after temporarily setting show-details=always in local development. Also remember that infrastructure probes often should stay minimal; detailed health is usually for secured human-facing diagnostics rather than every anonymous request.

If you return several details and none appear, try simplifying the indicator to a single obvious field such as withDetail("probe", "seen"). That helps distinguish between a registration problem and a visibility-policy problem. Once that works, add the real details back.

Common Pitfalls

The biggest mistake is assuming withDetail(...) forces the health endpoint to expose those fields publicly. It does not.

Another mistake is testing /actuator/health anonymously while the app is configured to show details only when authorized.

A third mistake is debugging the indicator code when the real issue is endpoint exposure, security, or health-group configuration.

Summary

• 'withDetail(...) adds data to the Health object, but Actuator may still hide it.'
• Check management.endpoint.health.show-details first.
• Make sure the health endpoint is exposed and your security rules allow the intended caller.
• Verify that you are calling the correct health endpoint or health group.
• If needed, temporarily use show-details=always in local development to confirm the indicator is working.