{"record":{"id":"3a2d6a7f06191b3c","repo":"brettwooldridge/HikariCP","slug":"failed-to-copy-hikariconfig-state-causemessage","errorCode":null,"errorMessage":"Failed to copy HikariConfig state: ${causeMessage}","messagePattern":"Failed to copy HikariConfig state: (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"src/main/java/com/zaxxer/hikari/HikariConfig.java","lineNumber":1033,"sourceCode":"   /**\n    * Copies the state of {@code this} into {@code other}.\n    *\n    * @param other Other {@link HikariConfig} to copy the state to.\n    */\n   @SuppressWarnings({\"rawtypes\", \"unchecked\"})\n   public void copyStateTo(HikariConfig other)\n   {\n      for (var field : HikariConfig.class.getDeclaredFields()) {\n         try {\n            if (!Modifier.isFinal(field.getModifiers())) {\n               field.setAccessible(true);\n               field.set(other, field.get(this));\n            } else if (field.getType().isAssignableFrom(AtomicReference.class)) {\n               ((AtomicReference) field.get(other)).set(((AtomicReference) field.get(this)).get());\n            }\n         }\n         catch (Exception e) {\n            throw new RuntimeException(\"Failed to copy HikariConfig state: \" + e.getMessage(), e);\n         }\n      }\n\n      other.sealed = false;\n   }\n\n   // ***********************************************************************\n   //                          Private methods\n   // ***********************************************************************\n\n   @SuppressWarnings(\"StatementWithEmptyBody\")\n   public void validate()\n   {\n      if (poolName == null) {\n         poolName = generatePoolName();\n      }\n      else if (isRegisterMbeans && poolName.contains(\":\")) {\n         throw new IllegalArgumentException(\"poolName cannot contain ':' when used with JMX\");","sourceCodeStart":1015,"sourceCodeEnd":1051,"githubUrl":"https://github.com/brettwooldridge/HikariCP/blob/a4d93f4f85517f90e632b795486d7102e933d7ff/src/main/java/com/zaxxer/hikari/HikariConfig.java#L1015-L1051","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Upgrade HikariCP to a version compatible with your JDK (5.x+ for Java 17+) — reflection handling was fixed for the module system","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","Read the wrapped cause in the stack trace: it names the exact field and access denial","Avoid calling copyStateTo yourself; it is effectively internal API — construct pools through the public constructors"],"exampleFix":"// before (JDK 17 + old HikariCP -> reflective access denied)\nHikariDataSource ds = new HikariDataSource(oldConfig); // RuntimeException: Failed to copy state\n\n// after\n// upgrade dependency\n<dependency>\n  <groupId>com.zaxxer</groupId><artifactId>HikariCP</artifactId><version>5.1.0</version>\n</dependency>","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n   sourceConfig.copyStateTo(targetConfig);\n} catch (RuntimeException e) {\n   throw new IllegalStateException(\"HikariCP state copy failed (likely module/reflection access: \" + e.getCause() + \"); check JDK --add-opens and HikariCP version\", e);\n}","preventionTips":["Use HikariCP 5.x+ on Java 17+ — module-system reflection issues were fixed there","Test pool construction on the exact JDK used in production, not only locally","Do not call copyStateTo from application code; treat it as internal and construct pools via public constructors"],"tags":["hikaricp","reflection","java-modules","jdk-compatibility","internal-api"],"backgroundTag":null,"analyzedSha":"a4d93f4f85517f90e632b795486d7102e933d7ff","analyzedAt":"2026-08-14T12:11:37.292Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}