brettwooldridge/HikariCP · error · IllegalArgumentException

poolName cannot contain ':' when used with JMX

Error message

poolName cannot contain ':' when used with JMX

What it means

During validate() — run when the pool starts — HikariCP generates a JMX ObjectName from poolName, and ':' is the ObjectName property separator, so a poolName containing ':' with isRegisterMbeans=true throws IllegalArgumentException. The check only fires when JMX registration is enabled; colons are otherwise acceptable.

Source

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

            throw new RuntimeException("Failed to copy HikariConfig state: " + e.getMessage(), e);
         }
      }

      other.sealed = false;
   }

   // ***********************************************************************
   //                          Private methods
   // ***********************************************************************

   @SuppressWarnings("StatementWithEmptyBody")
   public void validate()
   {
      if (poolName == null) {
         poolName = generatePoolName();
      }
      else if (isRegisterMbeans && poolName.contains(":")) {
         throw new IllegalArgumentException("poolName cannot contain ':' when used with JMX");
      }

      // treat empty property as null
      //noinspection NonAtomicOperationOnVolatileField
      catalog = getNullIfEmpty(catalog);
      connectionInitSql = getNullIfEmpty(connectionInitSql);
      connectionTestQuery = getNullIfEmpty(connectionTestQuery);
      transactionIsolationName = getNullIfEmpty(transactionIsolationName);
      dataSourceClassName = getNullIfEmpty(dataSourceClassName);
      dataSourceJndiName = getNullIfEmpty(dataSourceJndiName);
      driverClassName = getNullIfEmpty(driverClassName);
      jdbcUrl = getNullIfEmpty(jdbcUrl);

      // Check Data Source Options
      if (dataSource != null) {
         if (dataSourceClassName != null) {
            LOGGER.warn("{} - using dataSource and ignoring dataSourceClassName.", poolName);
         }

View on GitHub (pinned to a4d93f4f85)

Solutions

1. Remove ':' from the pool name — use '-', '_' or '.' as separators (e.g. 'prod-orders')
2. Or turn off JMX registration (registerMbeans=false) if MBeans are not needed
3. If multiple pools must be distinguished, keep names JMX-safe from the start

Example fix

# before
spring.datasource.hikari.pool-name=orders-db:5432
spring.datasource.hikari.register-mbeans=true # IllegalArgumentException at startup

# after
spring.datasource.hikari.pool-name=orders-db-5432
spring.datasource.hikari.register-mbeans=true

if (config.isRegisterMbeans() && poolName != null && poolName.contains(":")) {
   throw new IllegalArgumentException("poolName '" + poolName + "' contains ':' which is illegal with JMX registration");
}
config.setPoolName(poolName);

When it happens

Trigger: config.setPoolName("prod:orders") together with config.setRegisterMbeans(true); property files setting poolName with a host:port-style value; Spring Boot apps enabling MBean registration (spring.datasource.hikari.register-mbeans=true) with a colon-containing pool name.

Common situations: Naming pools after environments or hosts like 'db-replica:5432'; embedding URLs or service identifiers with colons in the pool name; enabling JMX for monitoring (Jolokia, Prometheus JMX exporter) on an existing app whose pool names already contain colons.

Related errors

• ${poolName} - is not suspendable
• connectionTimeout cannot be less than ${SOFT_TIMEOUT_FLOOR}m
• idleTimeout cannot be negative
• maxPoolSize cannot be less than 1
• minimumIdle cannot be negative

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