brettwooldridge/HikariCP · error · RuntimeException

Failed to copy HikariConfig state: ${causeMessage}

Error message

Failed to copy HikariConfig state: ${causeMessage}

What it means

copyStateTo(HikariConfig) copies every declared field of HikariConfig to another instance via reflection (setAccessible + field.set, with special handling for final AtomicReference fields). If any reflective access or write fails — normally a Java module-system or SecurityManager access denial to java.lang reflect, or an unexpected field type — the failure is wrapped as RuntimeException 'Failed to copy HikariConfig state: <cause>'. This is an internal plumbing error, not a config validation error.

Source

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

   /**
    * Copies the state of {@code this} into {@code other}.
    *
    * @param other Other {@link HikariConfig} to copy the state to.
    */
   @SuppressWarnings({"rawtypes", "unchecked"})
   public void copyStateTo(HikariConfig other)
   {
      for (var field : HikariConfig.class.getDeclaredFields()) {
         try {
            if (!Modifier.isFinal(field.getModifiers())) {
               field.setAccessible(true);
               field.set(other, field.get(this));
            } else if (field.getType().isAssignableFrom(AtomicReference.class)) {
               ((AtomicReference) field.get(other)).set(((AtomicReference) field.get(this)).get());
            }
         }
         catch (Exception e) {
            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");

View on GitHub (pinned to a4d93f4f85)

Solutions

1. Upgrade HikariCP to a version compatible with your JDK (5.x+ for Java 17+) — reflection handling was fixed for the module system
2. If you control the JVM command line, add the required --add-opens (e.g. --add-opens java.base/java.lang=ALL-UNNAMED) as indicated by the cause message
3. Read the wrapped cause in the stack trace: it names the exact field and access denial
4. Avoid calling copyStateTo yourself; it is effectively internal API — construct pools through the public constructors

Example fix

// before (JDK 17 + old HikariCP -> reflective access denied)
HikariDataSource ds = new HikariDataSource(oldConfig); // RuntimeException: Failed to copy state

// after
// upgrade dependency
<dependency>
  <groupId>com.zaxxer</groupId><artifactId>HikariCP</artifactId><version>5.1.0</version>
</dependency>

try {
   sourceConfig.copyStateTo(targetConfig);
} catch (RuntimeException e) {
   throw new IllegalStateException("HikariCP state copy failed (likely module/reflection access: " + e.getCause() + "); check JDK --add-opens and HikariCP version", e);
}

When it happens

Trigger: Calling new HikariDataSource(config) or HikariPool(config) where the constructor delegates to copyStateTo, under a JDK with strong encapsulation (Java 16+) where com.zaxxer.hikari is not open to reflective access; running with a SecurityManager that denies setAccessible; rare JVM/agent interference with reflection.

Common situations: Older HikariCP versions (pre-5.x, pre-JPMS hardening) run on Java 16+/17 without --add-opens java.base/java.lang=ALL-UNNAMED or the module not being open; custom classloader setups in application servers; tools (JaCoCo, mocking frameworks) interfering with reflection. Modern HikariCP releases ship module descriptors and this error is rare.

Related errors

• Failed to instantiate class ${credentialsProviderClassName}
• Failed to instantiate class ${exceptionOverrideClassName}
• Wrapped DataSource is not an instance of ${iface}
• Property %s does not exist on target %s
• Failed to load class ${className}

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