hibernate/hibernate-orm · error · UnknownProfileException

No fetch profile named '

Error message

No fetch profile named '

What it means

LoadQueryInfluencers.checkFetchProfileName() validates every fetch-profile name against the SessionFactory metadata before enabling or checking it; unknown names throw UnknownProfileException with the message 'No fetch profile named \'<name\>''. Fetch profiles are part of the mapping and must be declared at bootstrap — there is no runtime registration.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/engine/spi/LoadQueryInfluencers.java:291

//		final String parameterName = filterParameterName.substring( dot + 1 );
//		return new String[] { filterName, parameterName };
//	}


	// fetch profile support ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

	public boolean hasEnabledFetchProfiles() {
		return enabledFetchProfileNames != null && !enabledFetchProfileNames.isEmpty();
	}

	@Nonnull
	public Set<String> getEnabledFetchProfileNames() {
		return enabledFetchProfileNames == null ? emptySet() : enabledFetchProfileNames;
	}

	private void checkFetchProfileName(@Nonnull String name) {
		if ( !sessionFactory.containsFetchProfileDefinition( name ) ) {
			throw new UnknownProfileException( name );
		}
	}

	public boolean isFetchProfileEnabled(@Nonnull String name) throws UnknownProfileException {
		checkFetchProfileName( name );
		return enabledFetchProfileNames != null && enabledFetchProfileNames.contains( name );
	}

	public void enableFetchProfile(@Nonnull String name) throws UnknownProfileException {
		checkFetchProfileName( name );
		if ( enabledFetchProfileNames == null ) {
			enabledFetchProfileNames = new HashSet<>();
		}
		enabledFetchProfileNames.add( name );
	}

	public void disableFetchProfile(@Nonnull String name) throws UnknownProfileException {
		checkFetchProfileName( name );

View on GitHub (pinned to fad1729dce)

Solutions

1. Declare the profile in the mapping: @FetchProfile(name = "order.withItems", entityOverrides = @FetchProfile.FetchOverride(entity = Order.class, association = "items", fetch = FetchType.EAGER)) on the entity or package-info, or the equivalent <fetch-profile> XML
2. Verify the enabled name matches the declared name exactly (case-sensitive)
3. Guard with sessionFactory.containsFetchProfileDefinition(name) before enabling, so misconfiguration surfaces as your own clear error

Example fix

// before
session.enableFetchProfile("order-with-items"); // nothing declared -> UnknownProfileException

// after
@Entity
@FetchProfile(name = "order.withItems",
    entityOverrides = @FetchProfile.FetchOverride(entity = Order.class, association = "items", fetch = FetchType.EAGER))
public class Order { ... }
// ...
session.enableFetchProfile("order.withItems");

if (!sessionFactory.containsFetchProfileDefinition(profileName)) {
    throw new IllegalArgumentException("No fetch profile named '" + profileName + "' is defined in the SessionFactory");
}
session.enableFetchProfile(profileName);

try {
    session.enableFetchProfile(name);
} catch (UnknownProfileException e) {
    log.warn("Fetch profile '{}' is not defined; continuing without it", name);
}

When it happens

Trigger: session.enableFetchProfile(name) or session.isFetchProfileEnabled(name) with a name that has no @FetchProfile/@FetchProfile.FetchOverride annotation (on the entity or package-info) and no matching <fetch-profile> element in the ORM mapping XML.

Common situations: Typo or case mismatch in the profile name string; @FetchProfile annotation placed on a non-scanned class or missing the entity override; profile declared in a hbm.xml/orm.xml that is not listed in persistence.xml; package restructuring that dropped the annotated package-info from entity scanning.

Related errors

• Fetch profile object or name is null: %s
• Persistent class not known: {}
• Property not known: {}.{}
• The INSERT statement for table [%s] contains no column, and
• cannot recreate collection while filter is enabled: " + coll

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