{"record":{"id":"3c330f78cdb37316","repo":"hibernate/hibernate-orm","slug":"multiple-mutationexecutorservice-service-registrat","errorCode":null,"errorMessage":"Multiple MutationExecutorService service registrations found via ServiceLoader; specify one explicitly via 'hibernate.jdbc.mutation.executor'","messagePattern":"Multiple MutationExecutorService service registrations found via ServiceLoader; specify one explicitly via 'hibernate\\.jdbc\\.mutation\\.executor'","errorType":"exception","errorClass":"HibernateException","httpStatus":null,"severity":"critical","filePath":"hibernate-core/src/main/java/org/hibernate/engine/jdbc/mutation/internal/MutationExecutorServiceInitiator.java","lineNumber":83,"sourceCode":"\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 {\n\t\t\treturn null;\n\t\t}\n\t}\n\n\tprivate MutationExecutorService createStandardService(Map<String, Object> configurationValues) {\n\t\treturn new StandardMutationExecutorService( configurationValues );\n\t}\n}\n","sourceCodeStart":65,"sourceCodeEnd":98,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/engine/jdbc/mutation/internal/MutationExecutorServiceInitiator.java#L65-L98","documentation":"When hibernate.jdbc.mutation.executor is not set, MutationExecutorServiceInitiator discovers implementations via Java's ServiceLoader (META-INF/services/org.hibernate.engine.jdbc.mutation.spi.MutationExecutorService). If more than one implementation is discoverable on the classpath, Hibernate refuses to pick one arbitrarily and throws this HibernateException telling you to name the implementation explicitly.","triggerScenarios":"Two or more jars on the classpath each register a MutationExecutorService in their META-INF/services file — for example two internal platform libraries, or a library plus your own custom executor — while hibernate.jdbc.mutation.executor is unset.","commonSituations":"Shared platform/library jars that ship alternative mutation executors (e.g. batching or telemetry variants); fat jars merging service files; adding a second custom-executor jar without configuring the property.","solutions":["Set hibernate.jdbc.mutation.executor to the fully-qualified class name of the implementation you want","Or remove the duplicate registration: delete one of the META-INF/services entries / drop the redundant jar from the classpath","In fat-jar/assembly builds, verify service files are merged rather than overwritten silently (use a ServiceResourceTransformer)"],"exampleFix":"# before (ambiguous discovery)\n# (no property set; two jars provide implementations)\n\n# after\nhibernate.jdbc.mutation.executor=com.example.MyMutationExecutorService","handlingStrategy":"validation","validationCode":"// detect ambiguous service registrations before boot\nClassLoader cl = Thread.currentThread().getContextClassLoader();\nEnumeration<URL> urls = cl.getResources(\"META-INF/services/org.hibernate.engine.jdbc.mutation.spi.MutationExecutorService\");\nif (Collections.list(urls).size() > 1) {\n    // set hibernate.jdbc.mutation.executor explicitly or drop a jar\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Set hibernate.jdbc.mutation.executor whenever multiple provider jars exist","Use ServiceResourceTransformer in fat-jar builds","Review new dependencies for Hibernate SPI registrations"],"tags":["boot","service-loader","classpath","configuration","hibernate"],"backgroundTag":"duplicate-service-registrations","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}