hibernate/hibernate-orm · error · UnknownProfileException

No fetch profile named '{}'

Error message

No fetch profile named '{}'

What it means

Thrown when a natural-id load accessor (session.byNaturalId(...) / bySimpleNaturalId(...)) calls enableFetchProfile(name) with a name the SessionFactory does not know. Fetch profiles are registered only at bootstrap time from @FetchProfile annotations or hbm.xml <fetch-profile> elements; unknown names are rejected immediately instead of being silently ignored.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/loader/internal/BaseNaturalIdLoadAccessImpl.java:99


	protected Object with(Timeout timeout) {
		if ( lockOptions == null ) {
			lockOptions = new LockOptions();
		}
		lockOptions.setTimeOut( timeout.milliseconds() );
		return this;
	}

	public Object with(EntityGraph<T> graph, GraphSemantic semantic) {
		this.rootGraph = (RootGraphImplementor<T>) graph;
		this.graphSemantic = semantic;
		return this;
	}

	public Object enableFetchProfile(String profileName) {
		if ( !context.getSession().getFactory().containsFetchProfileDefinition( profileName ) ) {
			throw new UnknownProfileException( profileName );
		}
		if ( enabledFetchProfiles == null ) {
			enabledFetchProfiles = new HashSet<>();
		}
		enabledFetchProfiles.add( profileName );
		if ( disabledFetchProfiles != null ) {
			disabledFetchProfiles.remove( profileName );
		}
		return this;
	}

	public Object disableFetchProfile(String profileName) {
		if ( disabledFetchProfiles == null ) {
			disabledFetchProfiles = new HashSet<>();
		}
		disabledFetchProfiles.add( profileName );
		if ( enabledFetchProfiles != null ) {
			enabledFetchProfiles.remove( profileName );

View on GitHub (pinned to fad1729dce)

Solutions

  1. Check the spelling against the mapping and verify registration before enabling: sessionFactory.containsFetchProfileDefinition(name).
  2. Register the profile: @FetchProfile(name = "...", entityOverrides = @FetchProfile.EntityOverride(entity = MyEntity.class, associationOverrides = @FetchProfile.AssociationOverride(name = "assoc", fetch = FetchMode.JOIN))) on a mapped entity, or <fetch-profile> in hbm.xml.
  3. Make sure the annotated entity is actually in the persistence unit (persistence.xml, scanned package, or hibernate mapping list).

Example fix

// before: no profile registered, name misspelled
session.bySimpleNaturalId(User.class).enableFetchProfile("user-orders").load("john");

// after: profile exists on a mapped entity
// @FetchProfile(name = "user-with-orders",
//   entityOverrides = @FetchProfile.EntityOverride(entity = User.class,
//     associationOverrides = @FetchProfile.AssociationOverride(name = "orders", fetch = FetchMode.JOIN)))
// public class User { ... }
session.bySimpleNaturalId(User.class).enableFetchProfile("user-with-orders").load("john");
Defensive patterns

Strategy: validation

Validate before calling

String profile = "user-with-orders";
if ( !sessionFactory.containsFetchProfileDefinition( profile ) ) {
    throw new IllegalStateException( "Fetch profile not registered: " + profile );
}
var access = session.bySimpleNaturalId( User.class ).enableFetchProfile( profile );

Try / catch

try {
    access.enableFetchProfile( profile );
}
catch ( org.hibernate.UnknownProfileException e ) {
    // degrade gracefully: continue with default fetching
    log.warn( "Unknown fetch profile {}, falling back to default fetching", profile );
}

Prevention

When it happens

Trigger: Calling enableFetchProfile("profile") on a natural-id load access object when no @FetchProfile(name = "profile") exists on any mapped entity and no <fetch-profile name="profile"> exists in hbm.xml; a typo between mapping and query code; the profile annotated on a class that is not part of the persistence unit.

Common situations: Renaming a fetch profile in mappings but not in service code; @FetchProfile placed on a non-entity helper class or an entity excluded from scanning; hbm.xml files omitted from the mappings list; test SessionFactories built from a reduced entity set.

Related errors

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