{"record":{"id":"4c729b9a6ad832bb","repo":"hibernate/hibernate-orm","slug":"unsupported-jdbctype-nested-in-struct-4c729b","errorCode":null,"errorMessage":"Unsupported JdbcType nested in struct: ","messagePattern":"Unsupported JdbcType nested in struct: ","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/type/descriptor/jdbc/XmlHelper.java","lineNumber":954,"sourceCode":"\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t\telse {\n\t\t\t\t\t\tfor ( int i = 0; i < length; i++ ) {\n\t\t\t\t\t\t\tfinal Object arrayElement = Array.get( value, i );\n\t\t\t\t\t\t\tif ( arrayElement == null ) {\n\t\t\t\t\t\t\t\tappender.append( NULL_TAG );\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\telse {\n\t\t\t\t\t\t\t\tappender.append( START_TAG );\n\t\t\t\t\t\t\t\tconvertedBasicValueToString( appender, arrayElement, options, elementJavaType, elementJdbcType );\n\t\t\t\t\t\t\t\tappender.append( END_TAG );\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\tbreak;\n\t\t\tdefault:\n\t\t\t\tthrow new UnsupportedOperationException( \"Unsupported JdbcType nested in struct: \" + jdbcType );\n\t\t}\n\t}\n\n\tprivate static int getSelectableMapping(\n\t\t\tEmbeddableMappingType embeddableMappingType,\n\t\t\tString name) {\n\t\tfinal int selectableIndex = embeddableMappingType.getSelectableIndex( name );\n\t\tif ( selectableIndex == -1 ) {\n\t\t\tthrow new IllegalArgumentException(\n\t\t\t\t\tString.format(\n\t\t\t\t\t\t\t\"Could not find selectable [%s] in embeddable type [%s] for XML processing.\",\n\t\t\t\t\t\t\tname,\n\t\t\t\t\t\t\tembeddableMappingType.getMappedJavaType().getJavaTypeClass().getName()\n\t\t\t\t\t)\n\t\t\t);\n\t\t}\n\t\treturn selectableIndex;\n\t}","sourceCodeStart":936,"sourceCodeEnd":972,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/type/descriptor/jdbc/XmlHelper.java#L936-L972","documentation":"XmlHelper.convertedBasicValueToString serializes a fixed set of JDBC type families: numerics, booleans, chars/text, enums, dates/times/timestamps, binary, UUID, duration, and arrays. Writing an XML/struct aggregate that contains a nested value of any other JDBC kind falls into the default branch and throws UnsupportedOperationException.","triggerScenarios":"Persisting an entity whose XML or struct aggregate embeddable contains a field of an unsupported nested JdbcType, e.g. @JdbcTypeCode(SqlTypes.JSON), a nested SQLXML field, a raw STRUCT, spatial geometry (SqlTypes.GEOMETRY), or a vector type.","commonSituations":"Composing document types (JSON inside XML), adding spatial or vector fields to existing aggregate embeddables, custom JdbcTypes not covered by the switch.","solutions":["Map the nested value as a plain String attribute and serialize it in application code.","Move the exotic value out of the aggregate to its own column.","Upgrade Hibernate and re-test: the supported set grows across versions.","For custom JdbcTypes, contribute support upstream or pre-convert to a supported type."],"exampleFix":"// before\n@Embeddable\npublic class Doc {\n    String title;\n    @JdbcTypeCode(SqlTypes.JSON)\n    Map<String, Object> meta;   // -> Unsupported JdbcType nested in struct\n}\n// after: store the nested JSON as a string inside the aggregate\n@Embeddable\npublic class Doc {\n    String title;\n    String metaJson;            // serialize meta with Jackson yourself\n}","handlingStrategy":"validation","validationCode":"static final Set<Integer> NESTED_OK = Set.of(\n    SqlTypes.VARCHAR, SqlTypes.CHAR, SqlTypes.INTEGER, SqlTypes.BIGINT,\n    SqlTypes.DECIMAL, SqlTypes.DATE, SqlTypes.TIMESTAMP, SqlTypes.VARBINARY,\n    SqlTypes.UUID, SqlTypes.ARRAY /* ... */);\n\nstatic void assertNestedTypesSupported(EmbeddableMappingType t) {\n    t.forEachSelectable((i, s) -> {\n        if (!NESTED_OK.contains(s.getJdbcMapping().getJdbcType().getDefaultSqlTypeCode())) {\n            throw new IllegalStateException(\"Unsupported nested JDBC type: \" + s);\n        }\n    });\n}","typeGuard":null,"tryCatchPattern":"try {\n    session.persist(person);\n} catch (UnsupportedOperationException ex) {\n    if (ex.getMessage() != null && ex.getMessage().startsWith(\"Unsupported JdbcType nested in struct\")) {\n        throw new DataMappingException(\"Aggregate nests an unsupported JDBC type\", ex);\n    }\n    throw ex;\n}","preventionTips":["Do not embed JSON, SQLXML, geometry, or vector values inside XML/struct aggregates; store them as strings or separate columns.","Review aggregate field types in a startup check against the supported set.","Re-test aggregates after adding custom JdbcTypes to fields."],"tags":["hibernate","xml","struct","jdbc-type","unsupported-mapping"],"backgroundTag":"unsupported-jdbc-type","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}