hibernate/hibernate-orm · error · MappingException

Could not resolve named type: {}

Error message

Could not resolve named type: {}

What it means

BasicValue resolution of a named type (@Type("name"), hbm type attribute, or TypeDefinition name) failed to load the class: the ClassLoadingException is logged and the failure rethrown as this MappingException naming the unresolved type.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/mapping/BasicValue.java:939

				final var implicitDefinition =
						new TypeDefinition( name, typeNamedClass, null, null );
				context.getTypeDefinitionRegistry().register( implicitDefinition );
				return implicitDefinition.resolve(
						localTypeParams,
						getMutabilityPlan( explicitMutabilityPlanAccess, typeConfiguration ),
						context,
						stdIndicators
				);
			}

			return TypeDefinition.createLocalResolution( name, typeNamedClass, localTypeParams, context );
		}
		catch (ClassLoadingException e) {
			// allow the exception below to trigger
			CORE_LOGGER.couldNotResolveTypeName( name, e );
		}

		throw new MappingException( "Could not resolve named type: " + name );
	}

	private static <J> NamedBasicTypeResolution<J> getNamedBasicTypeResolution(
			Function<TypeConfiguration, MutabilityPlan<?>> explicitMutabilityPlanAccess,
			ConverterDescriptor<?,?> converterDescriptor,
			JpaAttributeConverterCreationContext converterCreationContext,
			BasicType<J> basicTypeByName,
			TypeConfiguration typeConfiguration) {
		final BasicValueConverter<J,?> valueConverter;
		final JavaType<J> domainJtd;
		if ( converterDescriptor != null ) {
			//noinspection unchecked
			valueConverter =
					(BasicValueConverter<J,?>)
							converterDescriptor.createJpaAttributeConverter( converterCreationContext );
			domainJtd = valueConverter.getDomainJavaType();
		}
		else {

View on GitHub (pinned to fad1729dce)

Solutions

1. Fix the fully-qualified name in @Type/@TypeDef.
2. Ensure the jar containing the type is on the runtime classpath (inspect the deployed artifact).
3. Prefer class literals (@Type(MyType.class), @TypeDef(typeClass = ...)) so the compiler validates references.

Example fix

// before
@Type("com.acme.PhneUserType") // typo
private Phone phone;

// after
@Type(PhoneUserType.class)
private Phone phone;

Class<?> t = Class.forName( "com.acme.PhoneUserType", false, getClass().getClassLoader() );
// run for every string-named custom type before building the SessionFactory

try {
    SessionFactory sf = configuration.buildSessionFactory();
}
catch ( MappingException e ) {
    // message: Could not resolve named type: <name>
    // fix the FQCN or add the missing jar to the runtime classpath
}

When it happens

Trigger: @Type("com.acme.PhoneUserType") with a typo or missing dependency; @TypeDef target class in a jar absent at runtime; hbm <type name="..."> referencing a class not on the classpath; JPMS/OSGi module not exporting the type's package.

Common situations: Shaded or trimmed runtime artifacts dropping optional dependencies; refactoring moves the custom type class; provided-scoped dependency needed at runtime; class visibility issues in modular runtimes.

Related errors

• %s
• Unable to load class [" + className + "]
• Embeddable class not found: {}
• Could not create DynamicParameterizedType for type: " + type
• Multiple active MetadataBuilder definitions were discovered

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