{"record":{"id":"2c1cd392468745c7","repo":"hibernate/hibernate-orm","slug":"unwrap-strategy-not-known-for-this-java-type-2c1cd3","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/UnknownBasicJavaType.java","lineNumber":69,"sourceCode":"\t\t}\n\t\telse {\n\t\t\treturn type;\n\t\t}\n\t}\n\n\t@Override\n\tpublic JdbcType getRecommendedJdbcType(JdbcTypeIndicators context) {\n\t\tthrow new JdbcTypeRecommendationException(\n\t\t\t\t\"Could not determine recommended JdbcType for Java type '\" + getTypeName() + \"'\"\n\t\t);\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\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() + \")\";","sourceCodeStart":51,"sourceCodeEnd":87,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/type/descriptor/java/spi/UnknownBasicJavaType.java#L51-L87","documentation":"UnknownBasicJavaType.unwrap() only supports a plain cast when the requested target type is assignable from the (never loaded) domain class; any other target throws UnsupportedOperationException('Unwrap strategy not known for this Java type'). Without the real Class, Hibernate cannot build an actual conversion. It fires at bind time when the chosen JdbcType needs the value in a different Java type.","triggerScenarios":"Reading or writing a column whose domain Java type resolved to UnknownBasicJavaType, while the selected JdbcType's binder/extractor requests a different Java type through WrapperOptions - e.g. a dialect whose getPreferredJavaTypeClass() differs from the domain class, or binding through java.sql.Array/String paths.","commonSituations":"Classpath/classloader mismatches at runtime (containers, hot reload, native image) where the type loads at bootstrap tooling time but not at runtime; custom mappings that depend on name-only type registration and then hit driver-specific conversions.","solutions":["Resolve the classpath/classloader problem so the real JavaType is registered and real unwrap strategies exist.","Register an explicit JavaType or AttributeConverter for the type so conversions are concrete.","Annotate the attribute with an explicit @JdbcType whose binder accepts a pass-through of the domain Java type."],"exampleFix":"// before: type only known by name; driver path needs String unwrap\nsession.createQuery(\"from E e where e.payload = :p\", E.class).setParameter(\"p\", payload);\n// unwrap -> UnsupportedOperationException: Unwrap strategy not known for this Java type\n\n// after: make the class loadable (fix classpath) and/or register the descriptor explicitly\npublic class MyPayloadJavaType extends AbstractJavaType<MyPayload> {\n    @Override\n    public <X> X unwrap(MyPayload value, Class<X> type, WrapperOptions options) {\n        if (String.class.isAssignableFrom(type)) return type.cast(value.toString());\n        throw unknownUnwrap(type);\n    }\n}","handlingStrategy":"validation","validationCode":"// After bootstrap, verify the descriptor for your domain type is real\nJavaType<?> jt = sessionFactory.getTypeConfiguration()\n        .getJavaTypeRegistry()\n        .findDescriptor(MyType.class);\nif (jt instanceof org.hibernate.type.descriptor.java.spi.UnknownBasicJavaType) {\n    throw new IllegalStateException(\"MyType did not load - fix the classpath before querying\");\n}","typeGuard":"static boolean isResolvedJavaType(JavaType<?> jt) {\n    return !(jt instanceof org.hibernate.type.descriptor.java.spi.UnknownBasicJavaType);\n}","tryCatchPattern":"try {\n    session.createQuery(\"from E e where e.payload = :p\", E.class)\n           .setParameter(\"p\", value).getResultList();\n} catch (UnsupportedOperationException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Unwrap strategy not known\")) {\n        // domain type was registered as UnknownBasicJavaType: fix classpath or register a JavaType/converter\n    } else {\n        throw e;\n    }\n}","preventionTips":["Smoke-test that every mapped type resolves to a real JavaType after SessionFactory build","Register converters for types drivers deliver as String/Number","Avoid name-only custom type registrations"],"tags":["hibernate","type-conversion","unwrap","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"}