hibernate/hibernate-orm · error · UnknownSqlResultSetMappingException

Unknown SqlResultSetMapping [" + resultSetMappingName + "]

Error message

Unknown SqlResultSetMapping [" + resultSetMappingName + "]

What it means

When resolving resultSetMapping names into an existing mapping, Util looks each name up in the SessionFactory's NamedObjectRepository. A null memento means no @SqlResultSetMapping was registered under that name, and it throws UnknownSqlResultSetMappingException with the offending name in brackets.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/procedure/internal/Util.java:79

		}
		else if ( !isEmpty( resultSetMappingClasses ) ) {
			resolveResultSetMappingClasses( resultSetMappingClasses, resultSetMapping, querySpaceConsumer, context );
		}

		// otherwise, nothing to resolve
	}

	public static void resolveResultSetMappingNames(
			String[] resultSetMappingNames,
			ResultSetMapping resultSetMapping,
			Consumer<String> querySpaceConsumer,
			ResultSetMappingResolutionContext context) {
		final var namedObjectRepository = context.getNamedObjectRepository();
		for ( String resultSetMappingName : resultSetMappingNames ) {
			final var memento =
					namedObjectRepository.getResultSetMappingMemento( resultSetMappingName );
			if ( memento == null ) {
				throw new UnknownSqlResultSetMappingException( "Unknown SqlResultSetMapping [" + resultSetMappingName + "]" );
			}
			memento.resolve( resultSetMapping, querySpaceConsumer, context );
		}
	}

	public static List<ResultSetMapping> resolveResultSetMappings(
			String procedureName,
			String[] resultSetMappingNames,
			Consumer<String> querySpaceConsumer,
			ResultSetMappingResolutionContext context) {
		final var namedObjectRepository = context.getNamedObjectRepository();
		final var sessionFactory = context.getSessionFactory();
		final List<ResultSetMapping> resultMappings = CollectionHelper.arrayList( resultSetMappingNames.length );
		for ( int i = 0; i < resultSetMappingNames.length; i++ ) {
			final var mappingName = resultSetMappingNames[i];
			final ResultSetMapping mapping = sessionFactory
					.getJdbcValuesMappingProducerProvider()
					.buildResultSetMapping( procedureName + ":" + mappingName, false, sessionFactory );

View on GitHub (pinned to fad1729dce)

Solutions

1. Define the mapping on an entity in the same persistence unit: @SqlResultSetMapping(name = "orderMapping", entities = @EntityResult(entityClass = Order.class))
2. Fix the reference so it matches the @SqlResultSetMapping name exactly (names are exact strings)
3. Ensure the class holding the mapping is registered — listed in persistence.xml or inside the scanned packages
4. Add a startup assertion that the memento resolves before the call is used

Example fix

// before
@NamedStoredProcedureQuery(name = "loadOrder", procedureName = "load_order",
    resultSetMappings = "orderMaping") // typo, mapping never found

// after
@SqlResultSetMapping(name = "orderMapping", entities = @EntityResult(entityClass = Order.class))
@NamedStoredProcedureQuery(name = "loadOrder", procedureName = "load_order",
    resultSetMappings = "orderMapping")

try {
    ProcedureCall call = session.createStoredProcedureCall("loadOrder", "orderMapping");
} catch (org.hibernate.UnknownSqlResultSetMappingException e) {
    // no @SqlResultSetMapping named "orderMapping" in this persistence unit:
    // define it on an entity, fix the typo, or include the defining class
}

When it happens

Trigger: createStoredProcedureCall("loadOrder", "orderMapping") / em.createStoredProcedureQuery("loadOrder", "orderMapping") where no @SqlResultSetMapping(name = "orderMapping") exists in the persistence unit; or @NamedStoredProcedureQuery(resultSetMappings = "orderMaping") with a typo.

Common situations: Typos between the reference and the @SqlResultSetMapping name; the mapping is defined on a class that is not part of the persistence unit (not scanned, not listed in persistence.xml); unit tests building a MetadataBuilder manually without the annotated class; mapping defined in an orm.xml file that is not included in the unit.

Related errors

• Cannot specify both result-set mapping names and classes
• Unknown SqlResultSetMapping [" + mappingName + "]
• Output type [%s] cannot be assigned to requested type [%s]
• JDBC driver does not support named parameters for setArray.
• GaussDB only supports REF_CURSOR parameters as the first par

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