{"record":{"id":"e676b487005afc12","repo":"hibernate/hibernate-orm","slug":"unexpected-json-type-type","errorCode":null,"errorMessage":"Unexpected JSON type \" + type","messagePattern":"Unexpected JSON type \" \\+ type","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/type/descriptor/jdbc/JsonHelper.java","lineNumber":298,"sourceCode":"\t\t\t\tcase NULL_VALUE:\n\t\t\t\t\tarrayList.add( null );\n\t\t\t\t\tbreak;\n\t\t\t\tcase NUMERIC_VALUE:\n\t\t\t\t\tarrayList.add( adapter.fromNumericValue(jdbcJavaType, elementJdbcType ,reader, options)  );\n\t\t\t\t\tbreak;\n\t\t\t\tcase BOOLEAN_VALUE:\n\t\t\t\t\tarrayList.add( reader.getBooleanValue() ? Boolean.TRUE : Boolean.FALSE );\n\t\t\t\t\tbreak;\n\t\t\t\tcase VALUE:\n\t\t\t\t\tarrayList.add( adapter.fromValue(jdbcJavaType, elementJdbcType ,reader, options) );\n\t\t\t\t\tbreak;\n\t\t\t\tcase OBJECT_START:\n\t\t\t\t\tassert elementJdbcType instanceof JsonJdbcType;\n\t\t\t\t\tfinal EmbeddableMappingType embeddableMappingType = ((JsonJdbcType) elementJdbcType).getEmbeddableMappingType();\n\t\t\t\t\tarrayList.add( consumeJsonDocumentItems(reader, embeddableMappingType, true, options) );\n\t\t\t\t\tbreak;\n\t\t\t\tdefault:\n\t\t\t\t\tthrow new UnsupportedOperationException( \"Unexpected JSON type \" + type );\n\t\t\t}\n\t\t}\n\n\t\tthrow new IllegalArgumentException( \"Expected JSON array end, but none found.\" );\n\t}\n\n\n\tprivate static class CustomArrayList extends AbstractCollection<Object> implements Collection<Object> {\n\t\tObject[] array = ArrayHelper.EMPTY_OBJECT_ARRAY;\n\t\tint size;\n\n\t\tpublic void ensureCapacity(int minCapacity) {\n\t\t\tint oldCapacity = array.length;\n\t\t\tif ( minCapacity > oldCapacity ) {\n\t\t\t\tint newCapacity = oldCapacity + ( oldCapacity >> 1 );\n\t\t\t\tnewCapacity = Math.max( Math.max( newCapacity, minCapacity ), 10 );\n\t\t\t\tarray = Arrays.copyOf( array, newCapacity );\n\t\t\t}","sourceCodeStart":280,"sourceCodeEnd":316,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/type/descriptor/jdbc/JsonHelper.java#L280-L316","documentation":"While reading the elements of a JSON array (deserializeArray), only VALUE, BOOLEAN_VALUE and OBJECT_START (nested json aggregate embeddables) are handled; every other item type falls to default and throws UnsupportedOperationException('Unexpected JSON type <type>'). In practice this means a structure the parser cannot represent - most notably nested arrays (ARRAY_START inside an array) - inside a JSON-mapped collection.","triggerScenarios":"Loading a JSON array attribute whose elements are themselves arrays (e.g., [[1,2],[3,4]]); any item type outside the supported set inside an array bound to a plural JSON mapping.","commonSituations":"Domain data modeled as nested arrays (matrix-like values) stored in a column mapped as List<T>; other services writing richer JSON than the mapping supports.","solutions":["Avoid nested arrays in json aggregate data: model each element as an embeddable object (list of aggregate embeddables) instead of an array of arrays.","Or flatten the structure to a single array and unpack positions in code."],"exampleFix":"// before: stored [[1,2],[3,4]] mapped as\n@JdbcTypeCode(SqlTypes.JSON) List<int[]> matrix; // parse -> Unexpected JSON type ARRAY_START\n\n// after: store objects the parser understands\n@JdbcTypeCode(SqlTypes.JSON) List<Row> matrix; // @Embeddable class Row { int x; int y; }","handlingStrategy":"validation","validationCode":"// Reject nested arrays before persisting (Jackson example)\nstatic void assertNoNestedArrays(com.fasterxml.jackson.databind.JsonNode arrayNode) {\n    for (JsonNode element : arrayNode) {\n        if (element.isArray()) {\n            throw new IllegalArgumentException(\"Nested arrays are not supported by Hibernate JSON collection parsing\");\n        }\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    return session.find(Product.class, id);\n} catch (UnsupportedOperationException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Unexpected JSON type\")) {\n        // unsupported item structure inside a JSON array (e.g., nested array): remodel as objects\n    } else {\n        throw e;\n    }\n}","preventionTips":["Model matrix-like data as a list of embeddable objects, not arrays of arrays","Validate outgoing JSON structures in the JsonFormatMapper","Test round-trips of complex JSON attributes before release"],"tags":["hibernate","json","unsupported-structure","nested-array","collection-mapping"],"backgroundTag":"unsupported-json-structure","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}