hibernate/hibernate-orm · error · IllegalArgumentException

Could not resolve named type : " + hibernateTypeName

Error message

Could not resolve named type : " + hibernateTypeName

What it means

When a <return-scalar/> declares a type attribute, ScalarDescriptor.resolve() looks the name up in the BasicTypeRegistry (resolutionContext.getTypeConfiguration().getBasicTypeRegistry().getRegisteredType(hibernateTypeName)). An unknown name yields null and this IllegalArgumentException is thrown. Only names registered as Hibernate basic types (built-ins like 'string', 'integer', 'uuid', plus any custom types contributed to the registry) are resolvable here.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/query/HbmResultSetMappingDescriptor.java:958

		}

		public ScalarDescriptor(JaxbHbmNativeQueryScalarReturnType hbmScalarReturn) {
			this( hbmScalarReturn.getColumn(), hbmScalarReturn.getType() );
		}

		@Nonnull
		@Override
		public ResultMementoBasicStandard resolve(@Nonnull ResultSetMappingResolutionContext resolutionContext) {
			BootQueryLogging.BOOT_QUERY_LOGGER.tracef(
					"Resolving HBM ScalarDescriptor into memento - %s",
					columnName
			);
			if ( hibernateTypeName != null ) {
				final var namedType =
						resolutionContext.getTypeConfiguration().getBasicTypeRegistry()
								.getRegisteredType( hibernateTypeName );
				if ( namedType == null ) {
					throw new IllegalArgumentException( "Could not resolve named type : " + hibernateTypeName );
				}
				return new ResultMementoBasicStandard( columnName, namedType );
			}
			else {
				// todo (6.0) : column name may be optional in HBM - double check
				return new ResultMementoBasicStandard( columnName, null );
			}
		}
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

1. Correct the type name to a registered Hibernate basic type (e.g. 'string', 'integer', 'big_decimal', 'uuid').
2. For custom types, register them via a TypeContributor / SupportedTypeContributor on the ServiceRegistry before this mapping is processed, or omit type and let Hibernate infer it.
3. Check the Hibernate version's list of built-in basic type names if migrating old mappings.

Example fix

<!-- before: 'monny' is not a registered type name -->
<return-scalar column="TOTAL" type="monny"/>

<!-- after -->
<return-scalar column="TOTAL" type="big_decimal"/>

// verify the type name against the registry before bootstrapping the mapping:
boolean known = bootstrapMetadata.getTypeConfiguration()
        .getBasicTypeRegistry()
        .getRegisteredType( hibernateTypeName ) != null;
if ( hibernateTypeName != null && !known ) {
    throw new IllegalStateException( "Unknown basic type name in mapping: " + hibernateTypeName );
}

catch ( IllegalArgumentException e ) {
    if ( e.getMessage().startsWith( "Could not resolve named type" ) ) {
        // replace the type attribute with a registered basic type name, or contribute the custom type first
    }
}

When it happens

Trigger: <return-scalar column="TOTAL" type="monny"/> (typo); using a custom UserType name that was never registered as a basic type in this bootstrap; using JDBC type names like 'VARCHAR' instead of Hibernate type names; version differences where a type name was renamed.

Common situations: Typos in type attributes; custom basic types contributed in one persistence unit but used in a mapping loaded by another; Hibernate 3/4 type names that no longer exist under Hibernate 6's type registry.

Related errors

• Cannot combine other returns with a collection return (" + r
• Illegal <return-join/> property attribute: '" + fullProperty
• Property join specified twice for join-return '" + ownerTabl
• Entity <return/> mapping did not specify entity name
• Entity <return/> mapping did not specify alias

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