{"record":{"id":"70e39e1fa58d45f7","repo":"hibernate/hibernate-orm","slug":"unwrap-strategy-not-known-for-this-java-type-70e39e","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/FormatMapperBasedJavaType.java","lineNumber":74,"sourceCode":"\t\t\t\t.toString( value, this, getWrapperOptions() );\n\t}\n\n\t@Override\n\tpublic T fromString(CharSequence string) {\n\t\treturn getFormatMapper( typeConfiguration )\n\t\t\t\t.fromString( string, this, getWrapperOptions() );\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\telse if ( type == String.class ) {\n\t\t\treturn type.cast( getFormatMapper( typeConfiguration )\n\t\t\t\t\t.toString( value, this, options ) );\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\tfinal var javaTypeClass = getJavaTypeClass();\n\t\tif ( javaTypeClass.isInstance( value ) ) {\n\t\t\treturn javaTypeClass.cast( value );\n\t\t}\n\t\telse if ( value instanceof String string ) {\n\t\t\treturn getFormatMapper( typeConfiguration )\n\t\t\t\t\t.fromString( string, this, options );\n\t\t}\n\t\tthrow new UnsupportedOperationException(\n\t\t\t\t\"Wrap strategy not known for this Java type: \" + getTypeName()\n\t\t);\n\t}","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/type/descriptor/java/spi/FormatMapperBasedJavaType.java#L56-L92","documentation":"unwrap() on a FormatMapperBasedJavaType supports exactly two targets: the mapped Java class itself (identity cast) and String (produced via the format mapper). Requesting any other type — byte[], driver-specific classes, other wrappers — throws UnsupportedOperationException, because JDBC-specific conversion belongs to the JdbcType.","triggerScenarios":"Generic binder/converter code calling unwrap(value, byte[].class or PGobject.class, options); custom JdbcTypes expecting a driver type from the JavaType; code ported from descriptors like StringJavaType that unwrap to many targets.","commonSituations":"Porting Hibernate 5 UserType implementations; custom dialect integrations; binary JSON handling where code reads values as byte arrays.","solutions":["Request only the mapped class or String from unwrap","Do JSON serialization via the format mapper, not unwrap","Move JDBC-type conversion into your JdbcType's binder, which owns driver types"],"exampleFix":"// before\nbyte[] b = javaType.unwrap(payload, byte[].class, options); // throws\n\n// after\nString json = javaType.unwrap(payload, String.class, options);\nbyte[] b = json.getBytes(java.nio.charset.StandardCharsets.UTF_8);","handlingStrategy":"type-guard","validationCode":"static boolean unwrapTargetOk(JavaType<?> jt, Class<?> target) {\n    return target.isAssignableFrom(jt.getJavaTypeClass()) || target == String.class;\n}","typeGuard":"static <X> boolean formatMapperUnwrapSupported(JavaType<?> jt, Class<X> target) {\n    return target == String.class || target.isAssignableFrom(jt.getJavaTypeClass());\n}","tryCatchPattern":"try {\n    X v = javaType.unwrap(value, target, options);\n} catch (UnsupportedOperationException e) {\n    String json = javaType.unwrap(value, String.class, options); // always-supported target\n    // convert json yourself to the type you actually wanted\n}","preventionTips":["Limit unwrap targets to the mapped class and String","Keep JDBC-type conversions inside the JdbcType's binder","Write contract tests enumerating supported unwrap targets for custom types"],"tags":["hibernate","orm","unwrap","json","custom-type"],"backgroundTag":"unsupported-type-conversion","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}