{"record":{"id":"50fd751a7736caa9","repo":"brettwooldridge/HikariCP","slug":"failed-to-instantiate-class-exceptionoverridecla","errorCode":null,"errorMessage":"Failed to instantiate class ${exceptionOverrideClassName}","messagePattern":"Failed to instantiate class (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"src/main/java/com/zaxxer/hikari/HikariConfig.java","lineNumber":949,"sourceCode":"      return this.exceptionOverrideClassName;\n   }\n\n   /**\n    * Set the user supplied SQLExceptionOverride class name.\n    *\n    * @param exceptionOverrideClassName the user supplied SQLExceptionOverride class name\n    * @see SQLExceptionOverride\n    */\n   public void setExceptionOverrideClassName(String exceptionOverrideClassName)\n   {\n      checkIfSealed();\n\n      try {\n         this.exceptionOverride = createInstance(exceptionOverrideClassName, SQLExceptionOverride.class);\n         this.exceptionOverrideClassName = exceptionOverrideClassName;\n      }\n      catch (Exception e) {\n         throw new RuntimeException(\"Failed to instantiate class \" + exceptionOverrideClassName, e);\n      }\n   }\n\n   /**\n    * Get the SQLExceptionOverride instance created by {@link #setExceptionOverrideClassName(String)} or specified by\n    * {@link #setExceptionOverride(SQLExceptionOverride)}.\n    *\n    * @return the SQLExceptionOverride instance, or null\n    * @see SQLExceptionOverride\n    */\n   public SQLExceptionOverride getExceptionOverride()\n   {\n      return this.exceptionOverride;\n   }\n\n   /**\n    * Set the user supplied SQLExceptionOverride instance.\n    *","sourceCodeStart":931,"sourceCodeEnd":967,"githubUrl":"https://github.com/brettwooldridge/HikariCP/blob/a4d93f4f85517f90e632b795486d7102e933d7ff/src/main/java/com/zaxxer/hikari/HikariConfig.java#L931-L967","documentation":"setExceptionOverrideClassName(String) reflectively loads and instantiates the named class as a SQLExceptionOverride; any failure (missing class, wrong type, missing no-arg constructor, constructor throw) is wrapped in a RuntimeException 'Failed to instantiate class <name>'. The override customizes which SQLExceptions HikariCP treats as pool-evicting, so a broken override must fail fast rather than fall back to defaults silently.","triggerScenarios":"Class name typo; class not shipped in the deployment artifact; class does not implement SQLExceptionOverride; only a parameterized constructor is defined; constructor performs work that fails in the target environment.","commonSituations":"Teams shipping a shared 'hikari-overrides' library that a service forgets as a dependency; renaming the override class during a refactor while config still references the old FQCN; constructor reading database/vault state that is unavailable during bean construction.","solutions":["Check the wrapped cause exception for the true failure (ClassNotFound vs InstantiationException vs constructor error)","Fix the FQCN in config to match the actual class, or ship the jar containing it","Give the class a public no-arg constructor and keep construction side-effect free","Prefer the type-safe alternative: setExceptionOverride(new MyOverride()) since you are compiling against the interface anyway"],"exampleFix":"// before\nconfig.setExceptionOverrideClassName(\"com.acme.MySqlExceptionOverride\"); // RuntimeException\n\n// after\nconfig.setExceptionOverride(new com.acme.MySqlExceptionOverride());","handlingStrategy":"try-catch","validationCode":"try {\n   Class.forName(overrideClassName).asSubclass(com.zaxxer.hikari.SQLExceptionOverride.class)\n       .getConstructor().newInstance();\n} catch (ReflectiveOperationException e) {\n   throw new IllegalStateException(\"SQLExceptionOverride unusable: \" + overrideClassName, e);\n}","typeGuard":null,"tryCatchPattern":"try {\n   config.setExceptionOverrideClassName(cls);\n} catch (RuntimeException e) {\n   log.error(\"Cannot install SQLExceptionOverride {} ({}); starting with default eviction behavior\", cls, e.getCause(), e);\n   // only continue without the override if that is acceptable\n}","preventionTips":["Prefer setExceptionOverride(new MyOverride()) — you already compile against the interface","Give overrides a public no-arg constructor and unit-test them separately from pool wiring","Verify the shared overrides library is a runtime dependency, not compile-only"],"tags":["hikaricp","configuration","reflection","exception-handling","classloading"],"backgroundTag":null,"analyzedSha":"a4d93f4f85517f90e632b795486d7102e933d7ff","analyzedAt":"2026-08-14T12:11:37.292Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}