{"record":{"id":"9f4995bee81466de","repo":"hibernate/hibernate-orm","slug":"callback-method-s-annotated-s-in-s-must-9f4995","errorCode":null,"errorMessage":"Callback method '%s' annotated '@%s' in '%s' must return void and have one parameter of type 'EntityAgent', 'EntityManager', or 'EntityManagerFactory'","messagePattern":"Callback method '(.+?)' annotated '@(.+?)' in '(.+?)' must return void and have one parameter of type 'EntityAgent', 'EntityManager', or 'EntityManagerFactory'","errorType":"exception","errorClass":"ModelsException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/models/spi/PersistenceUnitLifecycleEventHandler.java","lineNumber":157,"sourceCode":"\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tif ( namedMethod != null ) {\n\t\t\t\tvalidateSignature( listenerClassDetails, namedMethod, callbackAnnotation );\n\t\t\t}\n\t\t\tthrow new ModelsException( \"Persistence unit lifecycle callback method not found: \"\n\t\t\t\t\t\t\t\t\t\t+ lifecycleCallback.getMethodName()\n\t\t\t\t\t\t\t\t\t\t+ \" (\" + listenerClassDetails.getClassName() + \")\" );\n\t\t}\n\t}\n\n\tprivate static void validateSignature(\n\t\t\t@Nonnull ClassDetails listenerClassDetails,\n\t\t\t@Nonnull MethodDetails methodDetails,\n\t\t\t@Nonnull Class<? extends Annotation> callbackAnnotation) {\n\t\tif ( !hasValidSignature( methodDetails ) ) {\n\t\t\tthrow new ModelsException( \"Callback method '\"\n\t\t\t\t\t+ methodDetails.getName() + \"' annotated '@\"\n\t\t\t\t\t+ callbackAnnotation.getSimpleName() + \"' in '\"\n\t\t\t\t\t+ listenerClassDetails.getClassName()\n\t\t\t\t\t+ \"' must return void and have one parameter of type 'EntityAgent', 'EntityManager', or 'EntityManagerFactory'\");\n\t\t}\n\t}\n\n\tprivate static boolean hasValidSignature(@Nonnull MethodDetails methodDetails) {\n\t\treturn methodDetails.getArgumentTypes().size() == 1\n\t\t\t&& methodDetails.getReturnType() == ClassDetails.VOID_CLASS_DETAILS\n\t\t\t&& isPersistenceUnitLifecycleTarget( methodDetails.getArgumentTypes().get( 0 ) );\n\t}\n\n\tprivate static boolean isPersistenceUnitLifecycleTarget(@Nonnull ClassDetails argumentType) {\n\t\tfinal Class<?> javaClass = argumentType.toJavaClass();\n\t\treturn javaClass == EntityManagerFactory.class\n\t\t\t|| javaClass == EntityManager.class\n\t\t\t|| javaClass == EntityAgent.class;","sourceCodeStart":139,"sourceCodeEnd":175,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/models/spi/PersistenceUnitLifecycleEventHandler.java#L139-L175","documentation":"Error \"Callback method '%s' annotated '@%s' in '%s' must return void and have one parameter of type 'EntityAgent', 'EntityManager', or 'EntityManagerFactory'\" thrown in hibernate/hibernate-orm.","triggerScenarios":"A JPA entity-listener or lifecycle callback violates the callback contract.","commonSituations":"Listener classes with missing lifecycle annotations, wrong method signatures, or multiple methods for the same event type.","solutions":["Change the persistence-unit lifecycle callback to accept exactly one parameter of type EntityAgent, EntityManager, or EntityManagerFactory and return void."],"exampleFix":"Change the persistence-unit lifecycle callback to accept exactly one parameter of type EntityAgent, EntityManager, or EntityManagerFactory and return void.","handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}