{"record":{"id":"b259996f93cbca0f","repo":"hibernate/hibernate-orm","slug":"unrecognized-cast-target-type","errorCode":null,"errorMessage":"unrecognized cast target type: {}","messagePattern":"unrecognized cast target type: (.+?)","errorType":"exception","errorClass":"HibernateException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/type/spi/TypeConfiguration.java","lineNumber":374,"sourceCode":"\t\t\t//to UUID, but people will want to use it to cast from varchar, and that\n\t\t\t//won't work at all without some special casing in the Dialects\n//\t\t\tcase \"uuid\": return getBasicTypeForJavaType( UUID.class );\n\t\t\tdefault: {\n\t\t\t\tfinal var registeredBasicType = basicTypeRegistry.getRegisteredType( name );\n\t\t\t\tif ( registeredBasicType != null ) {\n\t\t\t\t\treturn registeredBasicType;\n\t\t\t\t}\n\n\t\t\t\ttry {\n\t\t\t\t\tfinal Class<?> javaTypeClass = scope.getClassLoaderService().classForName( name );\n\t\t\t\t\tfinal var jtd = javaTypeRegistry.resolveDescriptor( javaTypeClass );\n\t\t\t\t\tfinal var jdbcType = jtd.getRecommendedJdbcType( getCurrentBaseSqlTypeIndicators() );\n\t\t\t\t\treturn basicTypeRegistry.resolve( jtd, jdbcType );\n\t\t\t\t}\n\t\t\t\tcatch ( Exception ignore ) {\n\t\t\t\t}\n\n\t\t\t\tthrow new HibernateException( \"unrecognized cast target type: \" + name );\n\t\t\t}\n\t\t}\n\t}\n\n\t/**\n\t * Encapsulation of lifecycle concerns of a {@link TypeConfiguration}:\n\t * <ol>\n\t *     <li>\n\t *         \"Boot\" is where the {@link TypeConfiguration} is first built as\n\t *         {@linkplain org.hibernate.boot.model the boot model} of the domain\n\t *         model is converted into {@linkplain org.hibernate.metamodel.model\n\t *         the runtime model}. During this phase,\n\t *         {@link #getMetadataBuildingContext()} is accessible but\n\t *         {@link #getSessionFactory} throws an exception.\n\t *     </li>\n\t *     <li>\n\t *         \"Runtime\" is where the runtime model is accessible. During this\n\t *         phase, {@link #getSessionFactory()} is accessible but","sourceCodeStart":356,"sourceCodeEnd":392,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/type/spi/TypeConfiguration.java#L356-L392","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before - 'uuid' is not a recognized cast target\nList<UUID> ids = session.createQuery(\n        \"select cast(p.token as uuid) from Person p\", UUID.class ).list();\n\n// after - cast to string, convert in Java\nList<UUID> ids = session.createQuery(\n        \"select cast(p.token as string) from Person p\", String.class )\n        .list().stream().map( UUID::fromString ).toList();","handlingStrategy":"validation","validationCode":"static final Set<String> CAST_TARGETS = Set.of( \"string\", \"integer\", \"long\",\n    \"float\", \"double\", \"time\", \"date\", \"timestamp\", \"localtime\", \"localdate\",\n    \"localdatetime\", \"offsetdatetime\", \"zoneddatetime\", \"biginteger\", \"bigdecimal\",\n    \"duration\", \"instant\", \"binary\", \"boolean\", \"truefalse\", \"yesno\",\n    \"numericboolean\", \"json\", \"xml\" );\n\nstatic void checkCastTarget(String target) {\n    if ( !CAST_TARGETS.contains( target.toLowerCase( Locale.ROOT ) ) ) {\n        throw new IllegalArgumentException( \"Unsupported HQL cast target: \" + target );\n    }\n}","typeGuard":"static boolean isValidCastTarget(String name) {\n    return CAST_TARGETS.contains( name.toLowerCase( Locale.ROOT ) )\n        || name.contains( \".\" ); // FQCN of a registered JavaType\n}","tryCatchPattern":null,"preventionTips":["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."],"tags":["hibernate","hql","jpql","cast","type-resolution","query"],"backgroundTag":"hql-cast-type-unrecognized","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}