{"record":{"id":"016bca28f3ac3955","repo":"hibernate/hibernate-orm","slug":"unable-to-instantiate-custom-mutationexecutorservi","errorCode":null,"errorMessage":"Unable to instantiate custom MutationExecutorService : <className>","messagePattern":"Unable to instantiate custom MutationExecutorService : <className>","errorType":"exception","errorClass":"HibernateException","httpStatus":null,"severity":"critical","filePath":"hibernate-core/src/main/java/org/hibernate/engine/jdbc/mutation/internal/MutationExecutorServiceInitiator.java","lineNumber":71,"sourceCode":"\t\t\tfinal Class<? extends MutationExecutorService> customImplClass;\n\t\t\tif ( custom instanceof Class ) {\n\t\t\t\t//noinspection unchecked\n\t\t\t\tcustomImplClass = (Class<? extends MutationExecutorService>) custom;\n\t\t\t}\n\t\t\telse {\n\t\t\t\tcustomImplClass = classLoaderService.classForName( custom.toString() );\n\t\t\t}\n\n\t\t\ttry {\n\t\t\t\treturn customImplClass.getConstructor().newInstance();\n\t\t\t}\n\t\t\tcatch (NoSuchMethodException e) {\n\t\t\t\tthrow new HibernateException(\n\t\t\t\t\t\t\"Could not locate appropriate MutationExecutorService constructor : \" + customImplClass.getName(),\n\t\t\t\t\t\te );\n\t\t\t}\n\t\t\tcatch (Exception e) {\n\t\t\t\tthrow new HibernateException(\n\t\t\t\t\t\t\"Unable to instantiate custom MutationExecutorService : \" + customImplClass.getName(), e );\n\t\t\t}\n\t\t}\n\t}\n\n\tprivate static MutationExecutorService discover(ClassLoaderService classLoaderService) {\n\t\tfinal var discovered = classLoaderService.loadJavaServices( MutationExecutorService.class );\n\t\tfinal var iterator = discovered.iterator();\n\t\tif ( iterator.hasNext() ) {\n\t\t\tfinal var selected = iterator.next();\n\t\t\tif ( iterator.hasNext() ) {\n\t\t\t\tthrow new HibernateException(\n\t\t\t\t\t\t\"Multiple MutationExecutorService service registrations found via ServiceLoader; \"\n\t\t\t\t\t\t+ \"specify one explicitly via '\" + EXECUTOR_KEY + \"'\" );\n\t\t\t}\n\t\t\treturn selected;\n\t\t}\n\t\telse {","sourceCodeStart":53,"sourceCodeEnd":89,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/engine/jdbc/mutation/internal/MutationExecutorServiceInitiator.java#L53-L89","documentation":"MutationExecutorServiceInitiator's generic catch around customImplClass.getConstructor().newInstance(): instantiation failed for a reason other than a missing constructor — class or constructor not public (IllegalAccessException), constructor threw (InvocationTargetException), class is abstract, or another instantiation problem. Boot fails with HibernateException 'Unable to instantiate custom MutationExecutorService'.","triggerScenarios":"hibernate.jdbc.mutation.executor points at an abstract class, a non-public class/constructor, or a constructor whose body throws (e.g. it depends on services not yet available at boot time).","commonSituations":"Custom executors that read config or touch the service registry inside the constructor; refactoring that made the class abstract with a factory instead; classpath/visibility issues in module (JPMS) or OSGi deployments.","solutions":["Make the class concrete and public with a public no-arg constructor","Move any logic that can fail out of the constructor (lazy-initialize in initiateService/first use instead)","Read the InvocationTargetException cause in the stack trace — it carries the real exception your constructor threw","Verify the class is visible to Hibernate's ClassLoaderService (same classloader / proper module exports)"],"exampleFix":"// before: constructor does boot-time work\npublic MyExecutor() { this.pool = ServiceLocator.require(Pool.class); }\n\n// after: fail-safe constructor, lazy dependency\npublic MyExecutor() { }\nprivate Pool pool() { return ServiceLocator.require(Pool.class); }","handlingStrategy":"validation","validationCode":"// instantiate the custom executor in a pre-boot check\ntry {\n    Class.forName(executorClassName).getConstructor().newInstance();\n}\ncatch (ReflectiveOperationException e) {\n    throw new IllegalStateException(\"custom MutationExecutorService not instantiable\", e);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep constructors of custom services trivial; initialize lazily","Make the class public, concrete, with a public no-arg constructor","Ensure the class is visible to the application classloader"],"tags":["boot","instantiation","customization","reflection","hibernate"],"backgroundTag":"service-instantiation-failed","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}