{"record":{"id":"1544ac1a0990ed5c","repo":"apache/beam","slug":"unsupported-iterable-type-s-while-translating-row-to-struct","errorCode":null,"errorMessage":"Unsupported iterable type '%s' while translating row to struct.","messagePattern":"Unsupported iterable type '(.+?)' while translating row to struct\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/spanner/MutationUtils.java","lineNumber":408,"sourceCode":"        } else {\n          throw new IllegalArgumentException(\n              String.format(\"Unsupported logical type in iterable: %s\", identifier));\n        }\n        break;\n      case DATETIME:\n        if (iterable == null) {\n          mutationBuilder.set(column).toDateArray(null);\n        } else {\n          mutationBuilder\n              .set(column)\n              .toTimestampArray(\n                  StreamSupport.stream(iterable.spliterator(), false)\n                      .map(datetime -> Timestamp.parseTimestamp(datetime.toString()))\n                      .collect(toList()));\n        }\n        break;\n      default:\n        throw new IllegalArgumentException(\n            String.format(\n                \"Unsupported iterable type '%s' while translating row to struct.\",\n                beamIterableType.getTypeName()));\n    }\n  }\n\n  public static Row createRowFromMutation(Schema schema, Mutation mutation) {\n    Map<String, Object> mutationHashMap = new HashMap<>();\n    mutation\n        .asMap()\n        .forEach(\n            (column, value) -> mutationHashMap.put(column, convertValueToBeamFieldType(value)));\n    return Row.withSchema(schema).withFieldValues(mutationHashMap).build();\n  }\n\n  public static Object convertValueToBeamFieldType(Value value) {\n    switch (value.getType().getCode()) {\n      case BOOL:","sourceCodeStart":390,"sourceCodeEnd":426,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/spanner/MutationUtils.java#L390-L426","documentation":"The default case of the iterable-type switch in addIterableToMutationBuilder throws this IllegalArgumentException when the iterable element TypeName is not one of the supported array element types (STRING, INT64, BOOLEAN, FLOAT64, ROW, TIMESTAMP, DATE, logical/date-time variants). The row cannot be translated to a Spanner struct/mutation.","triggerScenarios":"Writing a Beam Row with an ITERABLE field whose collection element type is e.g. DOUBLE? bytes, FLOAT, INT16/INT32, MAP, or any other non-supported TypeName into Spanner via createMutationFromBeamRows.","commonSituations":"Nested arrays of byte arrays (BYTES), arrays of arrays (nested iterables), or arrays of uncommon numeric widths being written to Spanner, whose array element types are more restricted.","solutions":["Convert the iterable's elements to a supported Spanner array element type (STRING, INT64, FLOAT64, BOOLEAN, TIMESTAMP, DATE, or ROW/struct).","For nested iterables, flatten or serialize to a JSON string or a ROW array instead.","Inspect the offending TypeName from the message and add an explicit mapping in your pipeline before the Spanner write."],"exampleFix":"// before: ITERABLE<ITERABLE<INT32>> field\n// after: serialize nested list to JSON string row.apply(... via(r -> r.getIterable(\"cols\").toString()) ...)","handlingStrategy":"validation","validationCode":"java.util.Set<Schema.TypeName> ok = java.util.Set.of(\n  Schema.TypeName.STRING, Schema.TypeName.INT64, Schema.TypeName.BOOLEAN,\n  Schema.TypeName.DOUBLE, Schema.TypeName.ROW, Schema.TypeName.DATETIME, Schema.TypeName.LOGICAL_TYPE);\nif (!ok.contains(field.getType().getCollectionElementType().getTypeName())) {\n  throw new IllegalStateException(\"Iterable element type not supported: \"\n      + field.getType().getCollectionElementType().getTypeName());\n}","typeGuard":null,"tryCatchPattern":"try { createMutationFromBeamRows(schema, row, table); } catch (IllegalArgumentException e) { if (e.getMessage().contains(\"Unsupported iterable type\")) { /* re-map elements and retry */ } else throw e; }","preventionTips":["Restrict array element types to STRING/INT64/FLOAT64/BOOLEAN/TIMESTAMP/DATE/ROW","Flatten or JSON-encode nested collections","Keep a schema compatibility test in the pipeline suite"],"tags":["java","beam","spanner","iterable","unsupported-type"],"backgroundTag":"unsupported-operation","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}