{"record":{"id":"941f536e343e265e","repo":"hibernate/hibernate-orm","slug":"unknown-entityhandler-type-passed-handlertype-g","errorCode":null,"errorMessage":"Unknown EntityHandler type passed : {handlerType.getName()}","messagePattern":"Unknown EntityHandler type passed : (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/internal/SessionFactoryImpl.java","lineNumber":1285,"sourceCode":"\n\t@Override\n\tpublic void runInTransaction(@Nonnull Consumer<EntityManager> work) {\n\t\tinTransaction( work );\n\t}\n\n\t@Override\n\tpublic <H extends EntityHandler> void runInTransaction(\n\t\t\t@Nonnull Class<H> handlerType, @Nonnull Consumer<H> consumer) {\n\t\tif ( EntityManager.class.isAssignableFrom( handlerType ) ) {\n\t\t\t//noinspection unchecked\n\t\t\tinTransaction( (Consumer<EntityManager>) consumer );\n\t\t}\n\t\telse if ( EntityAgent.class.isAssignableFrom( handlerType ) ) {\n\t\t\t//noinspection unchecked\n\t\t\tinStatelessTransaction( (Consumer<EntityAgent>) consumer );\n\t\t}\n\t\telse {\n\t\t\tthrow new IllegalArgumentException( \"Unknown EntityHandler type passed : \" + handlerType.getName() );\n\t\t}\n\t}\n\n\t@Override\n\tpublic <R> R callInTransaction(@Nonnull Function<EntityManager, R> work) {\n\t\treturn fromTransaction( work );\n\t}\n\n\t@Override\n\tpublic <R, H extends EntityHandler> R callInTransaction(\n\t\t\t@Nonnull Class<H> handlerType, @Nonnull Function<H, R> function) {\n\t\tif ( EntityManager.class.isAssignableFrom( handlerType ) ) {\n\t\t\t//noinspection unchecked\n\t\t\treturn fromTransaction( (Function<EntityManager,R>) function );\n\t\t}\n\t\telse if ( EntityAgent.class.isAssignableFrom( handlerType ) ) {\n\t\t\t//noinspection unchecked\n\t\t\treturn fromStatelessTransaction( (Function<EntityAgent,R>) function );","sourceCodeStart":1267,"sourceCodeEnd":1303,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/internal/SessionFactoryImpl.java#L1267-L1303","documentation":"SessionFactory.runInTransaction(Class<H>, Consumer<H>) executes work with an EntityHandler of your choosing, but only two families exist: EntityManager (ORM session work) and EntityAgent (stateless session work). The method dispatches with isAssignableFrom on those two and throws IllegalArgumentException for anything else, so the handlerType must be the EntityManager/EntityAgent interfaces themselves or a subtype.","triggerScenarios":"Calling sessionFactory.runInTransaction(handlerType, consumer) where handlerType is neither EntityManager.class/EntityAgent.class nor a subclass — e.g. a custom interface, a mock class, or Object.class.","commonSituations":"Framework/abstraction code parameterizing the handler type generically and passing an arbitrary user interface; tests passing mock handler classes; discovering the new in-transaction API (Hibernate 7) and experimenting with custom handler types.","solutions":["Pass EntityManager.class for regular session work: runInTransaction(EntityManager.class, em -> ...)","Pass EntityAgent.class when you want stateless-session semantics: runInTransaction(EntityAgent.class, agent -> ...)","If you need a custom facade, wrap the EntityManager inside the lambda instead of passing your own class as handlerType","Guard custom dispatch code with the same isAssignableFrom checks before calling the API"],"exampleFix":"// before\npublic interface OrderRepo { void saveAll(List<Order> orders); }\nsessionFactory.runInTransaction(OrderRepo.class, repo -> ...); // IllegalArgumentException\n\n// after\nsessionFactory.runInTransaction(EntityManager.class, em -> {\n    OrderRepo repo = new OrderRepoImpl(em); // wrap inside the lambda\n    repo.saveAll(orders);\n});","handlingStrategy":"type-guard","validationCode":"if (!EntityManager.class.isAssignableFrom(handlerType)\n        && !EntityAgent.class.isAssignableFrom(handlerType)) {\n    throw new IllegalArgumentException(\n        \"handlerType must be EntityManager or EntityAgent, got \" + handlerType.getName());\n}\nsessionFactory.runInTransaction(handlerType, consumer);","typeGuard":"static boolean isSupportedHandler(Class<? extends EntityHandler> t) {\n    return EntityManager.class.isAssignableFrom(t)\n            || EntityAgent.class.isAssignableFrom(t);\n}","tryCatchPattern":"try {\n    sessionFactory.runInTransaction(handlerType, consumer);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"Unknown EntityHandler type\")) {\n        // default to EntityManager semantics\n        sessionFactory.runInTransaction(EntityManager.class, em -> consumer.accept((H) em));\n    } else throw e;\n}","preventionTips":["Pass exactly EntityManager.class or EntityAgent.class — the two supported constants","Build custom facades inside the lambda instead of inventing new handler types","Wrap generic dispatch code with the isAssignableFrom guard to fail with a clearer message"],"tags":["hibernate","entity-handler","in-transaction","api-misuse","argument-validation"],"backgroundTag":"unsupported-argument-type","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}