{"record":{"id":"4e61fe072c938ff3","repo":"hibernate/hibernate-orm","slug":"unwrap-strategy-not-known-for-this-java-type","errorCode":null,"errorMessage":"Unwrap strategy not known for this Java type: \" + getTypeName()","messagePattern":"Unwrap strategy not known for this Java type: \" \\+ getTypeName\\(\\)","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/type/descriptor/java/spi/EmbeddableAggregateJavaType.java","lineNumber":75,"sourceCode":"\t\t}\n\t\telse {\n\t\t\t// Otherwise use json by default for now\n\t\t\tfinal var descriptor = context.getJdbcType( SqlTypes.JSON );\n\t\t\tif ( descriptor != null ) {\n\t\t\t\treturn descriptor;\n\t\t\t}\n\t\t}\n\t\tthrow new JdbcTypeRecommendationException(\n\t\t\t\t\"Could not determine recommended JdbcType for `\" + getTypeName() + \"`\"\n\t\t);\n\t}\n\n\t@Override\n\tpublic <X> X unwrap(T value, Class<X> type, WrapperOptions options) {\n\t\tif ( type.isAssignableFrom( getJavaTypeClass() ) ) {\n\t\t\treturn type.cast( value );\n\t\t}\n\t\tthrow new UnsupportedOperationException(\n\t\t\t\t\"Unwrap strategy not known for this Java type: \" + getTypeName()\n\t\t);\n\t}\n\n\t@Override\n\tpublic <X> T wrap(X value, WrapperOptions options) {\n\t\tif ( value == null ) {\n\t\t\treturn null;\n\t\t}\n\t\telse {\n\t\t\tfinal var javaTypeClass = getJavaTypeClass();\n\t\t\tif ( javaTypeClass.isInstance( value ) ) {\n\t\t\t\treturn javaTypeClass.cast( value );\n\t\t\t}\n\t\t\tthrow new UnsupportedOperationException(\n\t\t\t\t\t\"Wrap strategy not known for this Java type: \" + getTypeName()\n\t\t\t);\n\t\t}","sourceCodeStart":57,"sourceCodeEnd":93,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/type/descriptor/java/spi/EmbeddableAggregateJavaType.java#L57-L93","documentation":"EmbeddableAggregateJavaType only unwraps a value to its own embeddable class — conversion to String, byte[] or driver types is the JdbcType's job (the format mapper serializes during binding). Calling unwrap() with any target type other than the embeddable's class throws UnsupportedOperationException.","triggerScenarios":"Binding an aggregate embeddable to a native-query parameter expecting a String; custom JdbcTypes or converters calling javaType.unwrap(value, String.class, options); generic serialization code that assumes unwrap-to-String works for every JavaType.","commonSituations":"Porting Hibernate 5 UserType contracts to the 6.x JavaType/JdbcType split; custom dialect integrations; copying unwrap patterns from StringJavaType which supports broader targets.","solutions":["Unwrap only to the embeddable's own class and let the JdbcType (e.g. JsonJdbcType) perform serialization","When you need a String outside the binder, serialize explicitly via the FormatMapper (Jackson/Gson)","For full manual control, map an AttributeConverter from the embeddable to String instead"],"exampleFix":"// before\nString json = embeddableJavaType.unwrap(address, String.class, options); // throws\n\n// after\nAddress a = embeddableJavaType.unwrap(address, Address.class, options);\nString json = formatMapper.toString(a, embeddableJavaType, options); // serialization is the mapper's job","handlingStrategy":"type-guard","validationCode":"static boolean canUnwrap(JavaType<?> jt, Class<?> target) {\n    return target.isAssignableFrom(jt.getJavaTypeClass()); // aggregate embeddables: own class only\n}","typeGuard":"static boolean unwrapSupported(JavaType<?> javaType, Class<?> target) {\n    return target.isAssignableFrom(javaType.getJavaTypeClass());\n}","tryCatchPattern":"try {\n    X v = javaType.unwrap(value, target, options);\n} catch (UnsupportedOperationException e) {\n    // rethrow with context: embeddable + requested target, so callers know serialization\n    // belongs to the JdbcType/FormatMapper, not unwrap()\n    throw new UnsupportedOperationException(\"unwrap to \" + target + \" unsupported for \"\n        + javaType.getJavaTypeClass().getName(), e);\n}","preventionTips":["Treat JavaType.unwrap as an internal binder hook, not a serialization API","Do embeddable-to-JSON serialization via the FormatMapper or your own ObjectMapper","Custom JdbcTypes own JDBC-type conversion; never expect it from unwrap()"],"tags":["hibernate","orm","unwrap","embeddable","json"],"backgroundTag":"unsupported-type-conversion","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}