brettwooldridge/HikariCP · error · IllegalStateException

cannot use setMetricsTrackerFactory() and setMetricRegistry(

Error message

cannot use setMetricsTrackerFactory() and setMetricRegistry() together

What it means

HikariCP supports two mutually exclusive ways to wire metrics: a MetricsTrackerFactory (custom programmatic SPI) or a MetricRegistry object (Dropwizard/metrics5/Micrometer registry). setMetricsTrackerFactory() throws IllegalStateException if a metricRegistry has already been set, because there would be no unambiguous destination for metrics. The check is one-directional here — setMetricRegistry() performs the mirror-image check.

Source

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

    * via {@link Connection#rollback()}.  Defaults to {@code false}.
    *
    * @param isolate {@code true} if internal pool queries should be isolated, {@code false} if not
    */
   public void setIsolateInternalQueries(boolean isolate)
   {
      checkIfSealed();
      this.isIsolateInternalQueries = isolate;
   }

   public MetricsTrackerFactory getMetricsTrackerFactory()
   {
      return metricsTrackerFactory;
   }

   public void setMetricsTrackerFactory(MetricsTrackerFactory metricsTrackerFactory)
   {
      if (metricRegistry != null) {
         throw new IllegalStateException("cannot use setMetricsTrackerFactory() and setMetricRegistry() together");
      }

      this.metricsTrackerFactory = metricsTrackerFactory;
   }

   /**
    * Get the MetricRegistry instance to use for registration of metrics used by HikariCP.  Default is {@code null}.
    *
    * @return the MetricRegistry instance that will be used
    */
   public Object getMetricRegistry()
   {
      return metricRegistry;
   }

   /**
    * Set a MetricRegistry instance to use for registration of metrics used by HikariCP.
    *

View on GitHub (pinned to a4d93f4f85)

Solutions

Choose one mechanism: pass the Micrometer/Dropwizard registry OR a custom MetricsTrackerFactory, never both
In Spring Boot, prefer letting Boot's autoconfiguration manage Hikari metrics via Micrometer instead of setting a factory manually
Audit the config assembly path (properties files, profile overlays, builders) for both keys being set
If you truly need custom behavior, implement it inside a MetricsTrackerFactory and drop the registry setting

Example fix

// before
config.setMetricRegistry(micrometerRegistry);
config.setMetricsTrackerFactory(customFactory); // IllegalStateException

// after (pick ONE)
config.setMetricsTrackerFactory(customFactory);
// or
config.setMetricRegistry(micrometerRegistry);

Defensive patterns

Strategy: validation

Validate before calling

if (config.getMetricRegistry() == null) {
   config.setMetricsTrackerFactory(factory);
} // else: registry already chosen, skip the factory

Prevention

Decide the metrics backend once at the architecture level; never mix registry and factory
In Spring Boot, let autoconfiguration own Hikari metrics and add custom metrics via Micrometer instead
Guard each metrics setter with a null check of the alternate property

When it happens

Trigger: Calling config.setMetricRegistry(registry) followed by config.setMetricsTrackerFactory(factory) (or the equivalent properties/micrometer autoconfiguration sequence). Common in Spring Boot apps where a Micrometer registry is auto-configured and application code then also installs a custom MetricsTrackerFactory on the same HikariConfig.

Common situations: Spring Boot with micrometer-core on the classpath auto-setting the registry, then custom code adding its own tracker factory; migrating metrics stacks (Dropwizard -> Micrometer) while old config remains; shared/copied HikariConfig objects receiving both settings from different modules.

Related errors

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