{"record":{"id":"d2d06ef2f621da22","repo":"hibernate/hibernate-orm","slug":"unknown-wrap-conversion-requested-conversiont","errorCode":null,"errorMessage":"Unknown wrap conversion requested: \" + conversionType.getName() + \" to \" + type.getTypeName()","messagePattern":"Unknown wrap conversion requested: \" \\+ conversionType\\.getName\\(\\) \\+ \" to \" \\+ type\\.getTypeName\\(\\)","errorType":"exception","errorClass":"HibernateException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/type/descriptor/java/AbstractJavaType.java","lineNumber":94,"sourceCode":"\n\t@Override\n\tpublic Comparator<T> getComparator() {\n\t\treturn comparator;\n\t}\n\n\t@Override\n\tpublic String extractLoggableRepresentation(T value) {\n\t\treturn (value == null) ? \"null\" : value.toString();\n\t}\n\n\tprotected HibernateException unknownUnwrap(Class<?> conversionType) {\n\t\tthrow new HibernateException(\n\t\t\t\t\"Unknown unwrap conversion requested: \" + type.getTypeName() + \" to \" + conversionType.getName()\n\t\t);\n\t}\n\n\tprotected HibernateException unknownWrap(Class<?> conversionType) {\n\t\tthrow new HibernateException(\n\t\t\t\t\"Unknown wrap conversion requested: \" + conversionType.getName() + \" to \" + type.getTypeName()\n\t\t);\n\t}\n}\n","sourceCodeStart":76,"sourceCodeEnd":99,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/type/descriptor/java/AbstractJavaType.java#L76-L99","documentation":"AbstractJavaType.unknownWrap is the mirror of unknownUnwrap: JavaType.wrap(value, options) hit a source class the descriptor cannot convert into its represented type. Thrown when a value coming from JDBC (or another source) must be wrapped into the descriptor's Java type and no conversion exists.","triggerScenarios":"A custom JavaType whose wrap() does not handle the concrete class of the incoming relational value - e.g. the driver returns java.math.BigInteger but the descriptor only wraps Integer; or reading a column through a descriptor registered for a different type.","commonSituations":"Driver/dialect returning unexpected JDBC classes (Oracle NUMBER as BigInteger, TIMESTAMP as oracle.sql.TIMESTAMP); custom JavaType with partial wrap() coverage; forcing a type on a native query result via addScalar(type) where the underlying value class differs.","solutions":["Broaden the custom JavaType's wrap() to cover the actual incoming classes (Number, String, java.util.Date, ...)","Adjust the native query/addScalar typing so the retrieved class matches what the descriptor wraps","Register/use a converter or a different descriptor that accepts the driver's actual class","Check the dialect/driver version if the incoming class changed after an upgrade"],"exampleFix":"// before\n@Override\npublic <X> Money wrap(X value, WrapperOptions options) {\n    if (value instanceof String s) return Money.parse(s);\n    return unknownWrap(value.getClass()); // driver sends BigDecimal\n}\n// after\n@Override\npublic <X> Money wrap(X value, WrapperOptions options) {\n    if (value instanceof String s) return Money.parse(s);\n    if (value instanceof Number n) return Money.of(n);\n    return unknownWrap(value.getClass());\n}","handlingStrategy":"type-guard","validationCode":"// when reading via native query + addScalar, confirm the driver's class is wrap-compatible\nObject raw = resultSet.getObject(column);\nif (!descriptorWraps(raw.getClass())) {\n    raw = resultSet.getString(column); // fall back to a form the descriptor wraps\n}","typeGuard":"// widen and check in a custom JavaType before delegating\nstatic boolean canWrap(Object value) {\n    return value == null || value instanceof String || value instanceof Number\n        || value instanceof java.util.Date || value instanceof byte[];\n}","tryCatchPattern":"try {\n    return session.createNativeQuery(\"select amt from t\", Money.class).getSingleResult();\n} catch (HibernateException e) {\n    if (String.valueOf(e.getMessage()).contains(\"Unknown wrap conversion requested\")) {\n        // the driver returned a class the descriptor lacks: map as String and parse in a converter\n    } else throw e;\n}","preventionTips":["Implement wrap() defensively for Number/String/java.util.Date rather than exact classes","Pin driver versions; test against the real database in CI so wrap targets match driver output","Prefer converters over custom JavaTypes when only domain mapping is needed","Log the incoming class in wrap failure paths for fast diagnosis"],"tags":["hibernate","orm","type-conversion","wrap","custom-type","jdbc-driver"],"backgroundTag":"unsupported-java-type-conversion","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}