{"record":{"id":"529d87bd444f5192","repo":"hibernate/hibernate-orm","slug":"wrap-strategy-not-known-for-this-java-type-ge-529d87","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/UnknownBasicJavaType.java","lineNumber":80,"sourceCode":"\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\tfinal var javaTypeClass = getJavaTypeClass();\n\t\tif ( javaTypeClass.isInstance( value ) ) {\n\t\t\treturn javaTypeClass.cast( value );\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 String toString() {\n\t\treturn \"BasicJavaType(\" + getTypeName() + \")\";\n\t}\n}\n","sourceCodeStart":62,"sourceCodeEnd":90,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/type/descriptor/java/spi/UnknownBasicJavaType.java#L62-L90","documentation":"UnknownBasicJavaType.wrap() throws UnsupportedOperationException('Wrap strategy not known for this Java type') when the incoming JDBC-side value is not an instance of the domain class - typically because the driver handed Hibernate a value in a different Java type (String, Number, driver class) and Hibernate cannot convert it without the loaded Class. It is the read-side mirror of the unwrap failure on the same unloadable-type descriptor.","triggerScenarios":"Extracting a column value into a domain type that resolved to UnknownBasicJavaType: the extractor produces e.g. a String or BigDecimal from the driver and calls wrap(value, options), which only succeeds on an exact instanceof match with the (unloadable) class.","commonSituations":"Runtime classloader differences so a type that 'worked' during bootstrap fails on read; hand-registered types by name; databases returning values in driver-specific Java types (Oracle TIMESTAMP, PGobject) that require conversion the placeholder descriptor cannot do.","solutions":["Fix class loading for the named type so a real JavaType with wrap strategies is used.","Register an AttributeConverter or a concrete JavaType for the property so driver values are converted explicitly.","Force a JdbcType whose extractor already returns the domain Java type (e.g. @JdbcTypeCode) to avoid the wrap step."],"exampleFix":"// before: column read into a name-only registered type\n@Entity public class Event {\n    @Type(\"org.acme.Payload\")  // class not loadable at runtime\n    @Column(name = \"payload\") Payload payload;\n}\n// read -> wrap -> UnsupportedOperationException: Wrap strategy not known for this Java type\n\n// after: register a converter so wrapping is explicit\n@Entity public class Event {\n    @Convert(converter = PayloadConverter.class)\n    @Column(name = \"payload\") String payloadJson;\n}","handlingStrategy":"validation","validationCode":"// Verify no mapped property resolved to a placeholder descriptor before use\nJavaType<?> jt = sessionFactory.getTypeConfiguration()\n        .getJavaTypeRegistry()\n        .findDescriptor(Payload.class);\nif (jt instanceof org.hibernate.type.descriptor.java.spi.UnknownBasicJavaType) {\n    throw new IllegalStateException(\"Payload.class unresolved - reads will fail in wrap()\");\n}","typeGuard":"static boolean isResolvedJavaType(JavaType<?> jt) {\n    return !(jt instanceof org.hibernate.type.descriptor.java.spi.UnknownBasicJavaType);\n}","tryCatchPattern":"try {\n    E e = session.find(E.class, id);\n} catch (UnsupportedOperationException ex) {\n    if (ex.getMessage() != null && ex.getMessage().startsWith(\"Wrap strategy not known\")) {\n        // driver delivered the value in a different Java type: fix the descriptor/converter for that attribute\n    } else {\n        throw ex;\n    }\n}","preventionTips":["Exercise one full read+write of every mapped type in a startup health check","Register AttributeConverters for driver-specific value types","Keep runtime classloader identical to bootstrap classloader"],"tags":["hibernate","type-conversion","wrap","classpath","java-type-descriptor"],"backgroundTag":"type-conversion-unsupported","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}