Introduction

When the /actuator endpoint returns 404 or 403, the usual causes are: the actuator dependency is missing, endpoints are not exposed over HTTP, Spring Security is blocking access, or the management port/base path has been changed. The fix depends on which issue applies — add the spring-boot-starter-actuator dependency, expose endpoints with management.endpoints.web.exposure.include=*, configure security to permit actuator paths, and check management.server.port and management.endpoints.web.base-path.

Step 1: Add the Dependency

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

// Gradle
implementation 'org.springframework.boot:spring-boot-starter-actuator'

Without this dependency, the /actuator endpoint does not exist.

Step 2: Expose Endpoints

By default, only health and info are exposed over HTTP. To expose all endpoints:

1# application.yml
2management:
3  endpoints:
4    web:
5      exposure:
6        include: "*"

# application.properties
management.endpoints.web.exposure.include=*

To expose specific endpoints:

1management:
2  endpoints:
3    web:
4      exposure:
5        include: health,info,metrics,env,beans
6        exclude: shutdown

Step 3: Configure Spring Security

If Spring Security is on the classpath, it blocks actuator endpoints by default:

1import org.springframework.context.annotation.Bean;
2import org.springframework.context.annotation.Configuration;
3import org.springframework.security.config.annotation.web.builders.HttpSecurity;
4import org.springframework.security.web.SecurityFilterChain;
5
6@Configuration
7public class SecurityConfig {
8
9    @Bean
10    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
11        http
12            .authorizeHttpRequests(auth -> auth
13                .requestMatchers("/actuator/health", "/actuator/info").permitAll()
14                .requestMatchers("/actuator/**").hasRole("ADMIN")
15                .anyRequest().authenticated()
16            )
17            .httpBasic(httpBasic -> {});
18        return http.build();
19    }
20}

For development, permit all actuator endpoints:

.requestMatchers("/actuator/**").permitAll()

Step 4: Check the Base Path

The default base path is /actuator. If it has been changed, you need to use the new path:

1management:
2  endpoints:
3    web:
4      base-path: /manage   # Now use /manage/health instead of /actuator/health

Check with:

curl http://localhost:8080/manage
curl http://localhost:8080/manage/health

Step 5: Check the Management Port

Actuator endpoints can be configured to run on a separate port:

management:
  server:
    port: 9090   # Actuator endpoints on port 9090

1# Application endpoints
2curl http://localhost:8080/api/users
3
4# Actuator endpoints (different port)
5curl http://localhost:9090/actuator/health

Step 6: Enable Specific Endpoints

Some endpoints are disabled by default (like shutdown):

1management:
2  endpoint:
3    shutdown:
4      enabled: true
5    env:
6      enabled: true
7    beans:
8      enabled: true
9  endpoints:
10    web:
11      exposure:
12        include: "*"

Verification Commands

1# Check if actuator is responding
2curl -v http://localhost:8080/actuator
3
4# Health endpoint (always available if actuator is present)
5curl http://localhost:8080/actuator/health
6
7# Detailed health info
8curl http://localhost:8080/actuator/health | python3 -m json.tool
9
10# List all available endpoints
11curl http://localhost:8080/actuator | python3 -m json.tool
12
13# Check specific endpoints
14curl http://localhost:8080/actuator/metrics
15curl http://localhost:8080/actuator/env
16curl http://localhost:8080/actuator/beans
17curl http://localhost:8080/actuator/info

Full Working Configuration

1# application.yml
2management:
3  endpoints:
4    web:
5      exposure:
6        include: "*"
7      base-path: /actuator
8  endpoint:
9    health:
10      show-details: always
11    shutdown:
12      enabled: false
13  info:
14    env:
15      enabled: true
16
17info:
18  app:
19    name: My Application
20    version: 1.0.0

Troubleshooting Checklist

Common Pitfalls

• Not quoting the wildcard * in YAML: In YAML, * is a special character (alias reference). Writing include: * without quotes causes a parsing error. Always quote it: include: "*" or use include: '*'.
• Exposing all endpoints in production without security: management.endpoints.web.exposure.include=* exposes sensitive information (environment variables, bean definitions, heap dumps). In production, expose only health and info, and protect others with authentication.
• Confusing exposure with enabled: management.endpoints.web.exposure.include controls HTTP visibility. management.endpoint.<name>.enabled controls whether the endpoint exists at all. An endpoint must be both enabled and exposed to be accessible.
• Using the wrong Spring Security configuration style: Spring Boot 3.x uses requestMatchers() and lambda-style configuration. Older antMatchers() and authorizeRequests() methods are removed. Using the old API causes compilation errors.
• Setting management.server.port and forgetting to update URLs: When actuator runs on a separate port (e.g., 9090), tools, load balancers, and health checks must point to the new port. The application port (8080) no longer serves actuator endpoints.

Summary

• Add spring-boot-starter-actuator dependency and expose endpoints with management.endpoints.web.exposure.include
• Configure Spring Security to permit actuator paths (at minimum /actuator/health)
• Check management.endpoints.web.base-path and management.server.port for custom configurations
• Quote the "*" wildcard in YAML configuration files
• In production, expose only necessary endpoints and protect sensitive ones with authentication