brettwooldridge/HikariCP · error · IllegalStateException

HealthCheckRegistry can only be set one time

Error message

HealthCheckRegistry can only be set one time

What it means

setHealthCheckRegistry() is a one-time, pre-start setting on HikariDataSource; calling it again after the pool started with a registry already bound throws IllegalStateException. Codahale/ Dropwizard health checks are registered into the live pool once, hence the restriction.

Source

Thrown at src/main/java/com/zaxxer/hikari/HikariDataSource.java:277

            throw new IllegalStateException("MetricsTrackerFactory can only be set one time");
         }
         else {
            p.setMetricsTrackerFactory(super.getMetricsTrackerFactory());
         }
      }
   }

   /** {@inheritDoc} */
   @Override
   public void setHealthCheckRegistry(Object healthCheckRegistry)
   {
      var isAlreadySet = getHealthCheckRegistry() != null;
      super.setHealthCheckRegistry(healthCheckRegistry);

      var p = pool;
      if (p != null) {
         if (isAlreadySet) {
            throw new IllegalStateException("HealthCheckRegistry can only be set one time");
         }
         else {
            p.setHealthCheckRegistry(super.getHealthCheckRegistry());
         }
      }
   }

   // ***********************************************************************
   //                        HikariCP-specific methods
   // ***********************************************************************

   /**
    * Returns {@code true} if the pool as been started and is not suspended or shutdown.
    *
    * @return {@code true} if the pool as been started and is not suspended or shutdown.
    */
   public boolean isRunning()
   {

View on GitHub (pinned to a4d93f4f85)

Solutions

1. Set the health check registry once before the pool starts (before first getConnection)
2. De-duplicate the code paths that attach a registry
3. Rebuild the DataSource if you truly need a different registry
4. Prefer declarative config (spring.datasource.hikari.health-check-registry or HikariConfig)

Example fix

// before
ds.setHealthCheckRegistry(registry1);
... pool starts ...
ds.setHealthCheckRegistry(registry2); // IllegalStateException

// after
cfg.setHealthCheckRegistry(registry2);
HikariDataSource ds = new HikariDataSource(cfg);

if (ds.getHealthCheckRegistry() == null) {
    ds.setHealthCheckRegistry(registry);
}

When it happens

Trigger: Calling setHealthCheckRegistry(...) twice while pool != null; Dropwizard health check wiring that runs after lazy pool start; multiple modules each trying to attach their HealthCheckRegistry.

Common situations: Dropwizard + HikariCP apps, Spring Boot with dropwizard-metrics on the classpath, repeated registration during config refresh.

Related errors

• Class must be an instance of com.codahale.metrics.health.Hea
• The configuration of the pool is sealed once started. Use Hi
• MetricRegistry can only be set one time
• MetricsTrackerFactory 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/4234482aba641b3f. Report an issue: GitHub.