{"record":{"id":"a4fe52df6e19b5e0","repo":"hibernate/hibernate-orm","slug":"could-not-determine-recommended-jdbctype-for-java-a4fe52","errorCode":null,"errorMessage":"Could not determine recommended JdbcType for Java type '\" + getTypeName() + \"'\"","messagePattern":"Could not determine recommended JdbcType for Java type '\" \\+ getTypeName\\(\\) \\+ \"'\"","errorType":"exception","errorClass":"JdbcTypeRecommendationException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/type/descriptor/java/spi/UnknownBasicJavaType.java","lineNumber":59,"sourceCode":"\t@Override\n\tpublic String getTypeName() {\n\t\treturn typeName;\n\t}\n\n\t@Override\n\tpublic Type getJavaType() {\n\t\tfinal Type type = super.getJavaType();\n\t\tif ( type == null ) {\n\t\t\tthrow new UnsupportedOperationException( \"Unloadable Java type: \" + typeName );\n\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 ) ) {","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/type/descriptor/java/spi/UnknownBasicJavaType.java#L41-L77","documentation":"UnknownBasicJavaType.getRecommendedJdbcType() throws JdbcTypeRecommendationException whenever Hibernate must infer a JDBC type for a basic attribute whose Java class was never loaded - the descriptor only stores the type name, so no recommendation is possible. It is the mapping-resolution-time symptom of the same unloadable-class problem as 'Unloadable Java type'.","triggerScenarios":"An attribute whose Java class failed to load (registered as UnknownBasicJavaType) combined with JDBC-type inference: schema validation/creation (hibernate.hbm2ddl.auto), binding, or mapping-model resolution asking the JavaType for its recommended JdbcType because no explicit @JdbcType/@JdbcTypeCode is set.","commonSituations":"The same classpath/classloader mismatches that produce 'Unloadable Java type' - offline tooling, containers, native image; custom basic types registered only by name in a TypeContributor; Hibernate version upgrades that changed where inference is triggered during bootstrap.","solutions":["Fix the underlying class-loading problem (class on classpath, correct name) - this exception is only a downstream symptom.","Pin the JDBC type explicitly so inference is skipped: @JdbcType, @JdbcTypeCode, or columnDefinition in orm.xml.","If it is a custom type, register a full BasicType/JavaType in a TypeContributor instead of relying on name-only resolution."],"exampleFix":"// before: Hibernate must infer the JdbcType for a type known only by name\n@Embeddable\npublic class Money {\n    @Column(name = \"currency\")\n    Currency currency; // resolved as UnknownBasicJavaType under a broken classloader\n}\n\n// after: declare the JDBC type explicitly to bypass inference\n@Column(name = \"currency\")\n@JdbcTypeCode(SqlTypes.VARCHAR)\nString currencyCode;","handlingStrategy":"try-catch","validationCode":"// Before bootstrap, confirm the Java type is actually loadable\ntry {\n    Class.forName(typeName, false, Thread.currentThread().getContextClassLoader());\n} catch (ClassNotFoundException e) {\n    throw new IllegalStateException(\"Cannot infer JDBC type; class missing: \" + typeName, e);\n}","typeGuard":null,"tryCatchPattern":"try {\n    metadata.buildSessionFactory();\n} catch (org.hibernate.type.descriptor.jdbc.JdbcTypeRecommendationException e) {\n    // message names the Java type whose JdbcType could not be inferred:\n    // make the class loadable or annotate the attribute with an explicit @JdbcType/@JdbcTypeCode\n}","preventionTips":["Annotate attributes with explicit @JdbcType/@JdbcTypeCode so inference is not required","Register custom types as full BasicType/JavaType, never name-only","Keep bootstrap and runtime classpaths identical"],"tags":["hibernate","jdbc-type","type-inference","classpath","bootstrap"],"backgroundTag":"jdbc-type-resolution-failed","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}