hibernate/hibernate-orm · error · HibernateException

Unable to locate proper event type for event name [

Error message

Unable to locate proper event type for event name [

What it means

HibernateException from EventType.resolveEventTypeByName when the name is non-null but absent from STANDARD_TYPE_BY_NAME_MAP — the map covers only the built-in EventType constants, not custom event types contributed through the EventEngine. The unknown name is echoed in the message; the exception means the string simply does not name any standard Hibernate event.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/event/spi/EventType.java:125

	}

	/**
	 * Find an {@link EventType} by its name
	 *
	 * @param eventName The name
	 *
	 * @return The {@link EventType} instance.
	 *
	 * @throws HibernateException If eventName is null, or if eventName does not correlate to any known event type.
	 */
	@Nonnull
	public static EventType<?> resolveEventTypeByName(@Nonnull final String eventName) {
		if ( eventName == null ) {
			throw new HibernateException( "event name to resolve cannot be null" );
		}
		final EventType<?> eventType = STANDARD_TYPE_BY_NAME_MAP.get( eventName );
		if ( eventType == null ) {
			throw new HibernateException( "Unable to locate proper event type for event name [" + eventName + "]" );
		}
		return eventType;
	}

	/**
	 * Get a collection of all the standard {@link EventType} instances.
	 */
	@Nonnull
	public static Collection<EventType<?>> values() {
		return STANDARD_TYPE_BY_NAME_MAP.values();
	}

	/**
	 * Used from {@link EventEngine} to "prime" the registered event-type map.
	 *
	 * Simply copy the values into its (passed) Map
	 */
	static void registerStandardTypes(@Nonnull Map<String, EventType<?>> eventTypes) {

View on GitHub (pinned to fad1729dce)

Solutions

1. Use an exact standard name from EventType's constants: auto-flush, create, delete, dirty-check, evict, flush, flush-entity, load, load-collection, lock, merge, persist, refresh, replicate, save, save-update, pre-collection-*, post-* (check the EventType source for the authoritative list)
2. For custom event types resolve via the SessionFactory's EventEngine: factory.getEventEngine().findRegisteredEventType(name)
3. Validate event-name strings at startup against EventType.values()/getRegisteredEventTypes() so typos fail fast with a list of valid names

Example fix

// before
EventType<?> t = EventType.resolveEventTypeByName("loads"); // typo -> Unable to locate proper event type for event name [loads]

// after
EventType<?> t = EventType.resolveEventTypeByName("load");

Set<String> valid = EventType.values().stream()
        .map(EventType::eventName).collect(Collectors.toSet());
if (!valid.contains(configuredName)) {
    throw new IllegalArgumentException("Unknown event type '" + configuredName + "'; valid: " + valid);
}
EventType<?> t = EventType.resolveEventTypeByName(configuredName);

boolean isKnownEventName(String name) {
    return EventType.values().stream().anyMatch(t -> t.eventName().equals(name));
}

try {
    EventType<?> t = EventType.resolveEventTypeByName(name);
} catch (HibernateException e) {
    if (e.getMessage() != null && e.getMessage().contains("Unable to locate proper event type")) {
        // log valid names and fail config validation with a helpful message
    }
    throw e;
}

When it happens

Trigger: A typo in an event name string — e.g. hibernate.cfg.xml <event type='loads'>, 'save-update' variants that no longer exist, or programmatic registry lookups by name; using resolveEventTypeByName for a custom event type that was contributed via EventEngineContributor (it will never be found here).

Common situations: Upgrading Hibernate across major versions where event names were added/removed/renamed; XML configs copied from old projects or blog posts; integrations resolving names from external config files that drift from the code's actual event types.

Related errors

• event name to resolve cannot be null
• The {storageEngine} storage engine is not supported
• Audit graph mutation plan used with non-graph action queue
• Audit graph mutation plan used with non-graph action queue
• Unknown ActionQueue implementation: %s. Valid values are 'gr

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