{"record":{"id":"0f01e7d0455e8f03","repo":"apache/beam","slug":"expected-iterable-for-array-field","errorCode":null,"errorMessage":"Expected Iterable for array field.","messagePattern":"Expected Iterable for array field\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/firestore/FirestoreUtils.java","lineNumber":272,"sourceCode":"      case BOOLEAN:\n        return value;\n      case DATETIME:\n        if (value instanceof Instant) {\n          return value;\n        }\n        if (value instanceof Number) {\n          return new Instant(((Number) value).longValue());\n        }\n        return Instant.parse(value.toString());\n      case BYTES:\n        if (value instanceof byte[]) {\n          return value;\n        }\n        return value.toString().getBytes(java.nio.charset.StandardCharsets.UTF_8);\n      case ARRAY:\n      case ITERABLE:\n        if (!(value instanceof Iterable)) {\n          throw new IllegalArgumentException(\"Expected Iterable for array field.\");\n        }\n        FieldType elementType = fieldType.getCollectionElementType();\n        if (elementType == null) {\n          throw new IllegalArgumentException(\"Collection element type cannot be null.\");\n        }\n        List<@Nullable Object> rowList = new ArrayList<>();\n        for (Object item : (Iterable<?>) value) {\n          rowList.add(convertFromJava(item, elementType));\n        }\n        return rowList;\n      case MAP:\n        if (!(value instanceof Map)) {\n          throw new IllegalArgumentException(\"Expected Map for map field.\");\n        }\n        FieldType valueType = fieldType.getMapValueType();\n        if (valueType == null) {\n          throw new IllegalArgumentException(\"Map value type cannot be null.\");\n        }","sourceCodeStart":254,"sourceCodeEnd":290,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/firestore/FirestoreUtils.java#L254-L290","documentation":"convertFromJava converts Java values (originating from Firestore Value protos) into Java objects matching the declared FieldType, when mapping documents to Rows. For ARRAY/ITERABLE fields the incoming value must already be an Iterable; any other object type breaks the conversion contract and throws IllegalArgumentException('Expected Iterable for array field.').","triggerScenarios":"Reading Firestore documents where a field declared as ARRAY/ITERABLE in the target Schema arrived as a scalar or map (e.g. schema was changed after the data was written, or the wrong schema was supplied to documentToRow/toRow).","commonSituations":"Schema drift: documents written earlier with scalar values now read with an array-typed schema; passing a document's map value directly instead of its list; mixing up field order when building Rows manually.","solutions":["Align the Row schema with the actual document field shape (list vs scalar) before conversion","Normalize scalar values to single-element lists upstream before writing","Read documents with their natural types first, then coerce with an explicit map transform","Fix the FieldType to match the stored data (e.g. FieldType.STRING instead of iterable)"],"exampleFix":"// before\nRow row = Row.withSchema(schema).addValues(\"not-a-list\").build(); // scalar in ARRAY slot\n// after\nRow row = Row.withSchema(schema).addValues(Collections.singletonList(\"tag\")).build();","handlingStrategy":"type-guard","validationCode":"Object v = row.getValue(\"tags\");\nif (v != null && !(v instanceof Iterable)) {\n  v = Collections.singletonList(v); // coerce scalar to list\n}","typeGuard":"static boolean isIterable(Object v) { return v instanceof Iterable; }","tryCatchPattern":"try {\n  Object out = convertFromJava(value, fieldType);\n} catch (IllegalArgumentException e) {\n  if (e.getMessage().contains(\"Expected Iterable\")) {\n    log.warn(\"Scalar where array expected; coercing\");\n  }\n}","preventionTips":["Coerce scalars to single-element lists upstream","Keep schemas in sync with the actual document shapes","Test reads against documents written by older schema versions"],"tags":["java","apache-beam","firestore","type-mismatch"],"backgroundTag":"type-mismatch","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}