brettwooldridge/HikariCP · error · IllegalArgumentException

Class must be an instance of com.codahale.metrics.health.Hea

Error message

Class must be an instance of com.codahale.metrics.health.HealthCheckRegistry

What it means

setHealthCheckRegistry(Object) accepts an Object so it can be set from generic configuration, but then requires (after optional JNDI resolution) that the object be a com.codahale.metrics.health.HealthCheckRegistry — the only health-check API HikariCP integrates with. Any other type throws IllegalArgumentException immediately. Note this setter additionally calls checkIfSealed(), so it also fails on a started pool.

Source

Thrown at src/main/java/com/zaxxer/hikari/HikariConfig.java:717

   {
      return healthCheckRegistry;
   }

   /**
    * Set the HealthCheckRegistry that will be used for registration of health checks by HikariCP.  Currently only
    * Codahale/DropWizard is supported for health checks.  Default is {@code null}.
    *
    * @param healthCheckRegistry the HealthCheckRegistry to be used
    */
   public void setHealthCheckRegistry(Object healthCheckRegistry)
   {
      checkIfSealed();

      if (healthCheckRegistry != null) {
         healthCheckRegistry = getObjectOrPerformJndiLookup(healthCheckRegistry);

         if (!(healthCheckRegistry instanceof HealthCheckRegistry)) {
            throw new IllegalArgumentException("Class must be an instance of com.codahale.metrics.health.HealthCheckRegistry");
         }
      }

      this.healthCheckRegistry = healthCheckRegistry;
   }

   public Properties getHealthCheckProperties()
   {
      return healthCheckProperties;
   }

   public void setHealthCheckProperties(Properties healthCheckProperties)
   {
      checkIfSealed();
      this.healthCheckProperties.putAll(healthCheckProperties);
   }

   public void addHealthCheckProperty(String key, String value)

View on GitHub (pinned to a4d93f4f85)

Solutions

1. Pass a com.codahale.metrics.health.HealthCheckRegistry instance (metrics-core codahale/dropwizard health)
2. If you want Spring Boot Actuator health, do not use this setter — HikariCP pools appear in Actuator via DataSourceHealthIndicator automatically
3. Verify the JNDI name / resolved object type before setting
4. If using dropwizard-metrics5 exclusively, accept that HikariCP health checks are not available for it

Example fix

// before
config.setHealthCheckRegistry("myJndiHealthName"); // resolves to wrong type -> IllegalArgumentException

// after
import com.codahale.metrics.health.HealthCheckRegistry;
config.setHealthCheckRegistry(new HealthCheckRegistry());

static boolean isHealthCheckRegistry(Object o) {
   return o == null || o instanceof com.codahale.metrics.health.HealthCheckRegistry;
}
// use: if (isHealthCheckRegistry(candidate)) config.setHealthCheckRegistry(candidate);

When it happens

Trigger: Passing a Dropwizard v5/metrics5 health registry, a Micrometer HealthEndpoint, a String class name, or a JNDI name resolving to something other than HealthCheckRegistry; passing null is fine (default).

Common situations: Assuming Micrometer health endpoints are supported like metric registries — they are not; app-server JNDI bindings with stale names resolving to a metric registry instead; mixing metrics5 (io.dropwizard.metrics5) with the codahale health API — health checks only support the codahale package.

Related errors

• Class must be instance of com.codahale.metrics.MetricRegistr
• cannot use setMetricsTrackerFactory() and setMetricRegistry(
• cannot use setMetricRegistry() and setMetricsTrackerFactory(
• HealthCheckRegistry can only be set one time
• connectionTimeout cannot be less than ${SOFT_TIMEOUT_FLOOR}m

AI-assisted analysis of brettwooldridge/HikariCP@a4d93f4f85 (2026-08-14). Data as JSON: /api/errors/83932c1d76e591ff. Report an issue: GitHub.