Introduction

When someone says "Spring Boot actuator /health is not working," the first thing to check is the actual endpoint path. In modern Spring Boot versions, the health endpoint is exposed at /actuator/health by default, so a request to plain /health usually fails unless you have customized the base path or mapped a health group to an additional path.

Start with the Dependency

The health endpoint does not exist unless Actuator is on the classpath.

For Gradle:

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-actuator")
}

For Maven:

1<dependency>
2    <groupId>org.springframework.boot</groupId>
3    <artifactId>spring-boot-starter-actuator</artifactId>
4</dependency>

If that dependency is missing, no actuator endpoints will appear regardless of your properties.

Use the Right URL

In current Spring Boot, the default health URL is:

/actuator/health

Test it directly:

curl http://localhost:8080/actuator/health

If you are trying http://localhost:8080/health and expecting it to work automatically, that mismatch alone may be the entire problem.

Check Exposure and Port Configuration

Actuator endpoints can be exposed on the main server port or a separate management port. They can also live under a customized base path.

Typical properties:

1management.endpoints.web.exposure.include=health,info
2management.endpoint.health.show-details=always
3management.server.port=8081
4management.endpoints.web.base-path=/actuator

With that configuration, the health endpoint is on port 8081, not the main application port:

curl http://localhost:8081/actuator/health

Many "not working" reports turn out to be requests sent to the wrong port or wrong base path.

Security Can Block It

If Spring Security is present and you define your own SecurityFilterChain, you are responsible for allowing access to the health endpoint if that is what you want.

A simple Boot 3 style example:

1import org.springframework.boot.actuate.autoconfigure.security.servlet.EndpointRequest;
2import org.springframework.boot.actuate.health.HealthEndpoint;
3import org.springframework.context.annotation.Bean;
4import org.springframework.context.annotation.Configuration;
5import org.springframework.security.config.Customizer;
6import org.springframework.security.config.annotation.web.builders.HttpSecurity;
7import org.springframework.security.web.SecurityFilterChain;
8
9@Configuration
10class SecurityConfig {
11
12    @Bean
13    SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
14        http
15            .authorizeHttpRequests(auth -> auth
16                .requestMatchers(EndpointRequest.to(HealthEndpoint.class)).permitAll()
17                .anyRequest().authenticated()
18            )
19            .httpBasic(Customizer.withDefaults());
20
21        return http.build();
22    }
23}

Without the right security rule, the endpoint may exist but return 401 or 403.

If You Really Need /health

If your infrastructure expects /health specifically, you can expose a health group at an additional path on the main server port.

management.endpoint.health.group.live.include=ping
management.endpoint.health.group.live.additional-path=server:/health

That gives you a dedicated /health path while preserving normal actuator conventions.

Look at the Logs and Response Code

The HTTP status code tells you a lot:

• '404 usually means wrong path, missing dependency, or wrong port'
• '401 or 403 usually means security configuration'
• '503 means the endpoint exists but one or more health indicators report a failing status'

Those are very different problems, so do not debug them the same way.

Common Pitfalls

The most common mistake is assuming the endpoint path is /health in all Spring Boot versions. For modern setups, /actuator/health is the default, and that difference matters immediately.

Another issue is forgetting that custom management ports and base paths change where the endpoint is served. If the application is on port 8080 and management is on 8081, probing the wrong port will always look broken.

Finally, teams often add a custom SecurityFilterChain and then assume Spring Boot will still expose health anonymously by magic. Once you take over security configuration, you must define the actuator access rules yourself.

Summary

• In modern Spring Boot, the default health URL is /actuator/health.
• Make sure spring-boot-starter-actuator is included.
• Check management port, base path, and endpoint exposure settings.
• Inspect security rules if the endpoint returns 401 or 403.
• Use an additional health-group path only if your infrastructure truly requires /health.