java.lang.ClassNotFoundException: io.micrometer.prometheus.PrometheusMeterRegistry

Q: Add the Prometheus registry dependency

When to use: Use this when you intend to scrape metrics using Prometheus.. Spring Boot needs the actual implementation JAR to instantiate the PrometheusMeterRegistry.

Q: Disable Prometheus export

When to use: Use this if you do not actually need Prometheus metrics.. Remove the property forcing Spring Boot to look for Prometheus.

Q: Switch to a different registry (e.g., Datadog)

When to use: Use this if you are migrating to a different monitoring backend.. Add the specific dependency for your new backend (e.g., Datadog) and update the properties.

Q: Check for dependency exclusions

When to use: Use this if you are sure the dependency is in your pom.xml.. A parent POM or another library might be accidentally excluding the micrometer dependency. Check your dependency tree.

Q: Rebuild and refresh IDE caches

When to use: Use this if the dependency was recently added but the IDE still throws the error.. IntelliJ or Eclipse might be using a stale index. Synchronize the project.

🔴 The Error You're Seeing

Confirm this matches your console output. If it does, you're in the right place.

ERROR LOG

2026-02-20 09:15:22.410 ERROR 8842 --- [           main] o.s.boot.SpringApplication               : Application run failed

java.lang.IllegalStateException: Failed to load ApplicationContext
...
Caused by: java.lang.ClassNotFoundException: io.micrometer.prometheus.PrometheusMeterRegistry
	at java.base/jdk.internal.loader.BuiltinClassLoader.loadClass(BuiltinClassLoader.java:641)

⚡ Quick Fix Works 80% of the time

Add the micrometer-registry-prometheus dependency to your pom.xml.

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>

🧠 Why this Happens

Tap to expand the deep technical explanation

You configured `management.metrics.export.prometheus.enabled=true` in your application.properties, which tells Spring Boot Actuator to look for the Prometheus MeterRegistry. However, the actual library that implements this registry (`micrometer-registry-prometheus`) is not on your classpath.

The HITEC City Parking Spot Analogy:

It's like ordering a specific brand of tires for your car, but the mechanic only has the rims. You told the system to expect Prometheus, but never bought the Prometheus package.

🔁 How to Reproduce Confirm this is your error

Create a Spring Boot app with Actuator. Set `management.metrics.export.prometheus.enabled=true`. Do NOT add the Prometheus dependency. Run the app.

🛠️ Solutions (5 Ways to Fix)

Solution 1✓ Most common cause

Add the Prometheus registry dependency

👉 Use this when you intend to scrape metrics using Prometheus.

Spring Boot needs the actual implementation JAR to instantiate the PrometheusMeterRegistry.

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>

Solution 2

Disable Prometheus export

👉 Use this if you do not actually need Prometheus metrics.

Remove the property forcing Spring Boot to look for Prometheus.

# application.properties
# Remove this line:
# management.metrics.export.prometheus.enabled=true

Solution 3

Switch to a different registry (e.g., Datadog)

👉 Use this if you are migrating to a different monitoring backend.

Add the specific dependency for your new backend (e.g., Datadog) and update the properties.

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-datadog</artifactId>
</dependency>

Solution 4

Check for dependency exclusions

👉 Use this if you are sure the dependency is in your pom.xml.

A parent POM or another library might be accidentally excluding the micrometer dependency. Check your dependency tree.

mvn dependency:tree | grep micrometer

Solution 5

Rebuild and refresh IDE caches

👉 Use this if the dependency was recently added but the IDE still throws the error.

IntelliJ or Eclipse might be using a stale index. Synchronize the project.

// Maven: mvn clean install
// IntelliJ: File -> Invalidate Caches and Restart

📋 Version Notes

Spring Boot 2.x

Uses Micrometer 1.x. Dependency is often managed by spring-boot-dependencies BOM.

Spring Boot 3.x

Uses Micrometer 1.11+. BOM still manages versions, but the registry dependency must be explicitly declared.

🛡️ How to Prevent This Next Time

When enabling a specific metrics backend in Spring Boot, always add the corresponding `micrometer-registry-*` dependency simultaneously.