{"record":{"id":"2a57d4861aca9726","repo":"hibernate/hibernate-orm","slug":"could-not-serialize-array-element","errorCode":null,"errorMessage":"Could not serialize array element","messagePattern":"Could not serialize array element","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/type/descriptor/jdbc/spi/JsonGeneratingVisitor.java","lineNumber":82,"sourceCode":"\t\t\tvisitBasicPluralValues( elementJavaType, elementJdbcType, values, options, writer );\n\t\t}\n\t\twriter.endArray();\n\t}\n\n\tprivate void visitPluralAggregateValues(\n\t\t\tAggregateJdbcType elementJdbcType,\n\t\t\tObject values,\n\t\t\tWrapperOptions options,\n\t\t\tJsonDocumentWriter writer) {\n\t\tfinal EmbeddableMappingType embeddableMappingType = elementJdbcType.getEmbeddableMappingType();\n\t\tif ( values.getClass().isArray() ) {\n\t\t\tfinal var length = Array.getLength( values );\n\t\t\tfor ( int j = 0; j < length; j++ ) {\n\t\t\t\ttry {\n\t\t\t\t\tvisit( embeddableMappingType, Array.get( values, j ), options, writer );\n\t\t\t\t}\n\t\t\t\tcatch (IOException e) {\n\t\t\t\t\tthrow new IllegalArgumentException( \"Could not serialize array element\", e );\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\telse if ( values instanceof Collection<?> collection ) {\n\t\t\tfor ( final var item : collection ) {\n\t\t\t\ttry {\n\t\t\t\t\tvisit( embeddableMappingType, item, options, writer );\n\t\t\t\t}\n\t\t\t\tcatch (IOException e) {\n\t\t\t\t\tthrow new IllegalArgumentException( \"Could not serialize array element\", e );\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\telse {\n\t\t\tthrow new IllegalArgumentException(\n\t\t\t\t\t\"Expected array or collection value, but got: \" + values.getClass().getName()\n\t\t\t);\n\t\t}","sourceCodeStart":64,"sourceCodeEnd":100,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/type/descriptor/jdbc/spi/JsonGeneratingVisitor.java#L64-L100","documentation":"JsonGeneratingVisitor serializes JSON aggregates, including arrays of embeddables. In the Java-array branch it visits each element; if the write throws IOException, it wraps the failure as IllegalArgumentException 'Could not serialize array element'. The original IOException is attached as the cause.","triggerScenarios":"Writing a JSON aggregate (JsonJdbcType / Oracle OSon path) that contains an array of embeddables, when the underlying JsonDocumentWriter fails mid-element - stream error, closed writer, or a failing nested value write.","commonSituations":"Custom JsonDocumentWriter sinks with lifecycle bugs; binding large aggregate arrays as query literals; OSon/JSON dialect types with writer constraints.","solutions":["Inspect the caused-by IOException to find the real sink failure and fix the writer lifecycle.","Keep the writer open for the whole serialization call; never share it across threads.","Shrink the aggregate array or bind parameters instead of literals for very large values."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    session.persist(order); // binds JSON aggregate with embeddable array\n} catch (IllegalArgumentException ex) {\n    if (\"Could not serialize array element\".equals(ex.getMessage()) && ex.getCause() instanceof IOException) {\n        throw new DataAccessException(\"JSON writer failed on aggregate array\", ex.getCause());\n    }\n    throw ex;\n}","preventionTips":["Read the caused-by IOException; the real failure is in the writer sink, not the domain model.","Keep one writer per serialization; close it only after the whole aggregate binds.","Avoid binding very large aggregate arrays as literals; use parameter binding."],"tags":["hibernate","json","json-aggregate","array-mapping","serialization"],"backgroundTag":"json-serialization-failed","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}