{"record":{"id":"7c51a643267c9b5e","repo":"hibernate/hibernate-orm","slug":"wrap-strategy-not-known-for-this-java-type-ge-7c51a6","errorCode":null,"errorMessage":"Wrap strategy not known for this Java type: \" + getTypeName()","messagePattern":"Wrap 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":89,"sourceCode":"\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}\n\n\t@Override\n\tpublic MutabilityPlan<T> getMutabilityPlan() {\n\t\tfinal var mutabilityPlan = super.getMutabilityPlan();\n\t\treturn mutabilityPlan == null ? this : mutabilityPlan;\n\t}\n\n\t@Override\n\tpublic boolean isMutable() {\n\t\treturn true;\n\t}\n\n\t@Override\n\tpublic T deepCopy(T value) {\n\t\treturn value == null ? null : fromString( toString( value ) );","sourceCodeStart":71,"sourceCodeEnd":107,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/type/descriptor/java/spi/FormatMapperBasedJavaType.java#L71-L107","documentation":"wrap() on a FormatMapperBasedJavaType accepts only null, instances of the mapped class, or a String that the format mapper deserializes. Any other input type — byte[], Map, driver JSONB objects — throws UnsupportedOperationException before any parsing happens.","triggerScenarios":"Custom extractors passing raw driver values (PGobject, byte[]) into wrap(); deserializing from binary JSONB payloads; generic hydration code assuming wrap accepts anything serializable.","commonSituations":"Hand-written ResultSet readers for JSON columns; legacy type implementations migrated from Hibernate 5; binary JSON columns read with getBytes() instead of getString().","solutions":["Pass the JSON String and let fromString deserialize it","Convert byte[] to String (UTF-8) before calling wrap","Use the standard JSON JdbcType extractor so correctly typed values reach wrap()"],"exampleFix":"// before\nPayload p = javaType.wrap(rs.getBytes(1), options); // byte[] -> throws\n\n// after\nPayload p = javaType.wrap(rs.getString(1), options); // String is deserialized by the mapper","handlingStrategy":"type-guard","validationCode":"static boolean wrapInputOk(JavaType<?> jt, Object value) {\n    return value == null || jt.getJavaTypeClass().isInstance(value) || value instanceof String;\n}","typeGuard":"static boolean formatMapperWrapSupported(JavaType<?> jt, Object v) {\n    return v == null || v instanceof String || jt.getJavaTypeClass().isInstance(v);\n}","tryCatchPattern":"try {\n    T v = javaType.wrap(raw, options);\n} catch (UnsupportedOperationException e) {\n    // convert raw to JSON text first, then let the format mapper deserialize\n    T v = javaType.wrap(raw instanceof byte[] b ? new String(b, java.nio.charset.StandardCharsets.UTF_8) : (String) raw, options);\n}","preventionTips":["Read JSON columns with getString(), not getBytes()/getObject()","Route deserialization through the format mapper","Validate input types in custom extractors before calling wrap()"],"tags":["hibernate","orm","wrap","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"}