{"record":{"id":"c229510c889821f9","repo":"apache/iceberg","slug":"unsupported-array-element-type-elementtype-c22951","errorCode":null,"errorMessage":"Unsupported array element type: ${elementType}","messagePattern":"Unsupported array element type: (.+?)","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/source/StructInternalRow.java","lineNumber":356,"sourceCode":"        return fillArray(\n            values,\n            array ->\n                (BiConsumer<Integer, Collection<?>>)\n                    (pos, list) ->\n                        array[pos] =\n                            collectionToArrayData(elementType.asListType().elementType(), list));\n      case MAP:\n        return fillArray(\n            values,\n            array ->\n                (BiConsumer<Integer, Map<?, ?>>)\n                    (pos, map) -> array[pos] = mapToMapData(elementType.asMapType(), map));\n      case VARIANT:\n        return fillArray(\n            values,\n            array -> (BiConsumer<Integer, Object>) (pos, v) -> array[pos] = toVariantVal(v));\n      default:\n        throw new UnsupportedOperationException(\"Unsupported array element type: \" + elementType);\n    }\n  }\n\n  private static VariantVal toVariantVal(Object value) {\n    if (value instanceof Variant) {\n      Variant variant = (Variant) value;\n      byte[] metadataBytes = new byte[variant.metadata().sizeInBytes()];\n      ByteBuffer metadataBuffer = ByteBuffer.wrap(metadataBytes).order(ByteOrder.LITTLE_ENDIAN);\n      variant.metadata().writeTo(metadataBuffer, 0);\n\n      byte[] valueBytes = new byte[variant.value().sizeInBytes()];\n      ByteBuffer valueBuffer = ByteBuffer.wrap(valueBytes).order(ByteOrder.LITTLE_ENDIAN);\n      variant.value().writeTo(valueBuffer, 0);\n\n      return new VariantVal(valueBytes, metadataBytes);\n    }\n\n    throw new UnsupportedOperationException(","sourceCodeStart":338,"sourceCodeEnd":374,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/spark/v4.0/spark/src/main/java/org/apache/iceberg/spark/source/StructInternalRow.java#L338-L374","documentation":"When StructInternalRow converts a nested collection (array) into Spark's ArrayData, it switches over the Iceberg element type and throws UnsupportedOperationException for element types it cannot encode. The default branch fires whenever an array's elementType falls outside the explicitly handled set (primitives, strings, decimal, date/timestamp, structs, maps, variants, etc.).","triggerScenarios":"Reading an Iceberg list column whose element type is not handled by collectionToArrayData — typically types added in newer Iceberg spec/versions than the installed Spark integration supports, reached during Spark reads via getArray(ordinal).","commonSituations":"Reading tables written by a newer Iceberg writer than the reader runtime; a stale iceberg-spark-runtime jar on the cluster classpath; schema evolution introducing a type variant unsupported by the installed Spark 4.0 module version.","solutions":["Upgrade the iceberg-spark-runtime jar to a version whose StructInternalRow supports the element type named in the message.","Check which Iceberg version wrote the table and ensure reader/writer version compatibility.","If the type cannot be supported, rewrite the column as a supported type (e.g. cast array elements) before reading.","Reproduce with the exact type name printed in the message and check Iceberg release notes for that type's Spark support."],"exampleFix":"// before (cluster classpath)\niceberg-spark-runtime-4.0_2.13-1.5.0.jar\n// after\niceberg-spark-runtime-4.0_2.13-1.7.0.jar // supports the array element type","handlingStrategy":"validation","validationCode":"Type elem = schema.findField(name).type().asListType().elementType();\nif (!isSupportedElementType(elem)) {\n  throw new UnsupportedOperationException(\"Upgrade Iceberg runtime to read array of \" + elem);\n}","typeGuard":"static boolean isSupportedElementType(Type t) {\n  switch (t.typeId()) {\n    case BOOLEAN: case INTEGER: case LONG: case FLOAT: case DOUBLE:\n    case DATE: case TIME: case TIMESTAMP: case STRING: case UUID:\n    case FIXED: case BINARY: case DECIMAL: case STRUCT: case LIST:\n    case MAP: case VARIANT:\n      return true;\n    default:\n      return false;\n  }\n}","tryCatchPattern":"try {\n  Dataset<Row> df = spark.read().format(\"iceberg\").load(tableIdent);\n} catch (UnsupportedOperationException e) {\n  if (e.getMessage().startsWith(\"Unsupported array element type\")) {\n    // upgrade runtime jar or rewrite column as a supported type\n  } else throw e;\n}","preventionTips":["Keep the Iceberg Spark runtime version >= the version that wrote the table.","Test reads of all nested types after table rewrites or format migrations.","Avoid experimental/custom types in shared production tables."],"tags":["spark","array","unsupported-type","reader-compatibility"],"backgroundTag":"unsupported-operation","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}