hibernate/hibernate-orm · error · HibernateException

Event listener '{}' must implement '{}'

Error message

Event listener '{}' must implement '{}'

What it means

Error "Event listener '{}' must implement '{}'" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/internal/MetadataImpl.java:516

				final String eventTypeName = propertyName.substring( EVENT_LISTENER_PREFIX.length() + 1 );
				final var eventType = EventType.resolveEventTypeByName( eventTypeName );
				final String listeners = (String) value;
				appendListeners( eventListenerRegistry, classLoaderService, listeners, eventType );
			}
		} );
	}

	private <T> void appendListeners(
			EventListenerRegistry eventListenerRegistry,
			ClassLoaderService classLoaderService,
			String listeners,
			EventType<T> eventType) {
		final var eventListenerGroup = eventListenerRegistry.getEventListenerGroup( eventType );
		for ( String listenerImpl : splitAtCommas( listeners ) ) {
			final var listener = instantiate( listenerImpl, classLoaderService );
			final var baseListenerInterface = eventType.baseListenerInterface();
			if ( !baseListenerInterface.isInstance( listener ) ) {
				throw new HibernateException( "Event listener '" + listenerImpl
						+ "' must implement '" + baseListenerInterface.getName() + "'");
			}
			eventListenerGroup.appendListener( baseListenerInterface.cast( listener ) );
		}
	}

	private static Object instantiate(String listenerImpl, ClassLoaderService classLoaderService) {
		try {
			return classLoaderService.classForName( listenerImpl ).newInstance();
		}
		catch (Exception e) {
			throw new HibernateException( "Could not instantiate event listener '" + listenerImpl + "'", e );
		}
	}

	@Override
	public void visitRegisteredComponents(Consumer<Component> consumer) {
		composites.forEach( consumer );

View on GitHub (pinned to fad1729dce)

Solutions

1. Make the listener class implement the expected Hibernate event listener interface (e.g. PreInsertEventListener).
2. Register the listener under the correct event type that matches the interfaces it implements.
3. Check for classloading issues where the listener was compiled against a different Hibernate version.

When it happens

Trigger: A configured event listener class does not implement the required listener interface.

Common situations: Registering a listener for an event type (e.g. PreInsertEventListener) whose class does not implement that interface.

AI-assisted analysis of hibernate/hibernate-orm@fad1729dce (2026-08-22). Data as JSON: /api/errors/499653fe6ea01b04. Report an issue: GitHub.