What causes "unrecognized cast target type: {}" in hibernate/hibernate-orm?

Cast to one of the recognized basic type names, e.g. cast(x as string), cast(x as biginteger), cast(x as instant), and convert further in Java.

hibernate/hibernate-orm · error · HibernateException

unrecognized cast target type: {}

Error message

unrecognized cast target type: {}

What it means

TypeConfiguration.castType(String) (TypeConfiguration.java:313-377) resolves the target type of an HQL cast(x as <name>). It accepts a fixed set of names (string, integer, long, float, double, time, date, timestamp, localtime, localdate, localdatetime, offsetdatetime, zoneddatetime, biginteger, bigdecimal, duration, instant, binary, boolean, truefalse, yesno, numericboolean, json, xml), then registered basic type names, then any fully-qualified class name that resolves to a registered JavaType with a recommended JdbcType. Anything else - including 'uuid', which is deliberately disabled in the source - throws this HibernateException.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/type/spi/TypeConfiguration.java:374

			//to UUID, but people will want to use it to cast from varchar, and that
			//won't work at all without some special casing in the Dialects
//			case "uuid": return getBasicTypeForJavaType( UUID.class );
			default: {
				final var registeredBasicType = basicTypeRegistry.getRegisteredType( name );
				if ( registeredBasicType != null ) {
					return registeredBasicType;
				}

				try {
					final Class<?> javaTypeClass = scope.getClassLoaderService().classForName( name );
					final var jtd = javaTypeRegistry.resolveDescriptor( javaTypeClass );
					final var jdbcType = jtd.getRecommendedJdbcType( getCurrentBaseSqlTypeIndicators() );
					return basicTypeRegistry.resolve( jtd, jdbcType );
				}
				catch ( Exception ignore ) {
				}

				throw new HibernateException( "unrecognized cast target type: " + name );
			}
		}
	}

	/**
	 * Encapsulation of lifecycle concerns of a {@link TypeConfiguration}:
	 * <ol>
	 *     <li>
	 *         "Boot" is where the {@link TypeConfiguration} is first built as
	 *         {@linkplain org.hibernate.boot.model the boot model} of the domain
	 *         model is converted into {@linkplain org.hibernate.metamodel.model
	 *         the runtime model}. During this phase,
	 *         {@link #getMetadataBuildingContext()} is accessible but
	 *         {@link #getSessionFactory} throws an exception.
	 *     </li>
	 *     <li>
	 *         "Runtime" is where the runtime model is accessible. During this
	 *         phase, {@link #getSessionFactory()} is accessible but

View on GitHub (pinned to fad1729dce)

Solutions

Cast to one of the recognized basic type names, e.g. cast(x as string), cast(x as biginteger), cast(x as instant), and convert further in Java.
For UUIDs, cast to string in HQL and call UUID.fromString in Java - the uuid cast target is intentionally not supported (TypeConfiguration.java:355-358).
If you cast to a class, use its fully qualified name and ensure a JavaType is registered for it (most basic JDK types are; enums and entities are not cast targets).
Check the spelling/case of built-in names - they are matched as lower-case literals listed in TypeConfiguration.java:330-354.

Example fix

// before - 'uuid' is not a recognized cast target
List<UUID> ids = session.createQuery(
        "select cast(p.token as uuid) from Person p", UUID.class ).list();

// after - cast to string, convert in Java
List<UUID> ids = session.createQuery(
        "select cast(p.token as string) from Person p", String.class )
        .list().stream().map( UUID::fromString ).toList();

Defensive patterns

Strategy: validation

Validate before calling

static final Set<String> CAST_TARGETS = Set.of( "string", "integer", "long",
    "float", "double", "time", "date", "timestamp", "localtime", "localdate",
    "localdatetime", "offsetdatetime", "zoneddatetime", "biginteger", "bigdecimal",
    "duration", "instant", "binary", "boolean", "truefalse", "yesno",
    "numericboolean", "json", "xml" );

static void checkCastTarget(String target) {
    if ( !CAST_TARGETS.contains( target.toLowerCase( Locale.ROOT ) ) ) {
        throw new IllegalArgumentException( "Unsupported HQL cast target: " + target );
    }
}

Type guard

static boolean isValidCastTarget(String name) {
    return CAST_TARGETS.contains( name.toLowerCase( Locale.ROOT ) )
        || name.contains( "." ); // FQCN of a registered JavaType
}

Prevention

Remember 'uuid' is deliberately not a cast target - cast to string and convert in Java.
Never cast to enums or entity names; convert after the query instead.
Validate dynamic HQL cast targets against the supported list before executing user-built queries.
Use the exact lower-case names from TypeConfiguration.castType when generating HQL.

When it happens

Trigger: Running HQL like cast(e.token as uuid) (explicitly unsupported per the comment at TypeConfiguration.java:355-358), cast(e.status as MyEnum) or cast(x as SomeEntity); typos such as cast(x as Bigint) or cast(x as str); a target whose Java class is not registered in the JavaTypeRegistry or has no recommended JdbcType.

Common situations: Porting SQL to HQL and assuming the database's cast targets exist (uuid, varchar, int variants); trying to cast to enums or entity types; upgrading Hibernate where a previously tolerated cast target now resolves strictly.

Related errors

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