{"record":{"id":"b162579173eb2828","repo":"hibernate/hibernate-orm","slug":"could-not-convert-s-to-s-using-s-to-unwra","errorCode":null,"errorMessage":"Could not convert '%s' to '%s' using '%s' to unwrap","messagePattern":"Could not convert '(.+?)' to '(.+?)' using '(.+?)' to unwrap","errorType":"exception","errorClass":"HibernateException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/type/descriptor/java/JavaTypeHelper.java","lineNumber":16,"sourceCode":"/*\n * SPDX-License-Identifier: Apache-2.0\n * Copyright Red Hat Inc. and Hibernate Authors\n */\npackage org.hibernate.type.descriptor.java;\n\nimport jakarta.annotation.Nullable;\nimport org.hibernate.HibernateException;\nimport org.hibernate.type.descriptor.java.spi.UnknownBasicJavaType;\n\n/**\n * @author Steve Ebersole\n */\npublic class JavaTypeHelper {\n\tprotected static <T extends JavaType<?>> HibernateException unknownUnwrap(Class<?> sourceType, Class<?> targetType, T jtd) {\n\t\tthrow new HibernateException(\n\t\t\t\t\"Could not convert '\" + sourceType.getName()\n\t\t\t\t\t\t+ \"' to '\" + targetType.getName()\n\t\t\t\t\t\t+ \"' using '\" + jtd.getClass().getName() + \"' to unwrap\"\n\t\t);\n\t}\n\n\tprotected static <T extends JavaType<?>> HibernateException unknownWrap(Class<?> valueType, Class<?> sourceType, T jtd) {\n\t\tthrow new HibernateException(\n\t\t\t\t\"Could not convert '\" + valueType.getName()\n\t\t\t\t\t\t+ \"' to '\" + sourceType.getName()\n\t\t\t\t\t\t+ \"' using '\" + jtd.getClass().getName() + \"' to wrap\"\n\t\t);\n\t}\n\n\tpublic static boolean isTemporal(@Nullable JavaType<?> javaType) {\n\t\treturn javaType != null && javaType.isTemporalType();\n\t}\n","sourceCodeStart":1,"sourceCodeEnd":34,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/type/descriptor/java/JavaTypeHelper.java#L1-L34","documentation":"JavaTypeHelper.unknownUnwrap builds the HibernateException('Could not convert X to Y using Z to unwrap') thrown by JavaType.unwrap implementations when asked to convert a domain value to a class they do not support. unwrap runs at bind time to turn domain values into JDBC-friendly types (String, Long, java.sql types), so this error means the registered JavaType cannot produce what the JdbcType or binding context requested.","triggerScenarios":"A custom JavaType/UserType whose unwrap handles only one branch (e.g. only String.class) being used with a JdbcType that requests another type; @JavaType/@JdbcType/@Type combinations that do not line up; parameter binding forcing a different unwrap target; an unresolved UnknownBasicJavaType being asked to unwrap.","commonSituations":"Registering a custom type but pairing it with the wrong column/JdbcType; Hibernate upgrades that added new unwrap targets; mixing @Type with @JdbcTypeCode on the same attribute; native query parameters with unexpected Java types.","solutions":["Read the message: it names sourceType, targetType, and the JavaType class — add the missing branch to that type's unwrap","Fix the mapping: align @JavaType with the actual attribute type and @JdbcType/@JdbcTypeCode with the actual column","Prefer extending AbstractJavaType or Hibernate's basic-type bases so unsupported paths degrade predictably","If the type is an UnknownBasicJavaType, the JavaType was never resolved — register or annotate the type properly"],"exampleFix":"// before\n@Override\npublic <X> X unwrap(Color value, Class<X> type, WrapperOptions options) {\n    if (type == String.class) return (X) value.name();\n    throw unknownUnwrap(type, Color.class, this); // any other target dies\n}\n\n// after\n@Override\npublic <X> X unwrap(Color value, Class<X> type, WrapperOptions options) {\n    if (value == null) return null;\n    if (type == String.class) return (X) value.name();\n    if (type == Integer.class) return (X) Integer.valueOf(value.getRGB());\n    throw unknownUnwrap(type, Color.class, this);\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    session.persist(entity);\n} catch (HibernateException ex) {\n    if (ex.getMessage() != null && ex.getMessage().endsWith(\"to unwrap\")) {\n        // mapping bug: the named JavaType lacks the unwrap branch — fix the type/mapping\n    }\n}","preventionTips":["Cover every unwrap target your JdbcType can request; keep unknownUnwrap as the last line","Test custom types against the exact JdbcType you deploy","Avoid mixing @Type, @JavaType and @JdbcTypeCode on one attribute"],"tags":["hibernate","custom-type","unwrap","type-mapping"],"backgroundTag":"type-unwrap-conversion-unsupported","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}