{"record":{"id":"8f75634e88eba9b4","repo":"apache/beam","slug":"exploded-field-s-must-be-an-iterable-type-got-s","errorCode":null,"errorMessage":"Exploded field %s must be an iterable type, got %s.","messagePattern":"Exploded field (.+?) must be an iterable type, got (.+?)\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/schemas/transforms/providers/JavaExplodeTransformProvider.java","lineNumber":123,"sourceCode":"  }\n\n  /** A {@link SchemaTransform} for Explode. */\n  protected static class ExplodeTransform extends SchemaTransform {\n\n    private final Configuration configuration;\n\n    ExplodeTransform(Configuration configuration) {\n      this.configuration = configuration;\n    }\n\n    @Override\n    public PCollectionRowTuple expand(PCollectionRowTuple input) {\n      Schema inputSchema = input.get(INPUT_ROWS_TAG).getSchema();\n      Schema.Builder outputSchemaBuilder = new Schema.Builder();\n      for (Schema.Field field : inputSchema.getFields()) {\n        if (configuration.getFields().contains(field.getName())) {\n          if (field.getType().getCollectionElementType() == null) {\n            throw new IllegalArgumentException(\n                String.format(\n                    \"Exploded field %s must be an iterable type, got %s.\",\n                    field.getName(), field.getType()));\n          } else {\n            outputSchemaBuilder =\n                outputSchemaBuilder.addField(\n                    field.getName(), field.getType().getCollectionElementType());\n          }\n        } else {\n          outputSchemaBuilder = outputSchemaBuilder.addField(field);\n        }\n      }\n      Schema outputSchema = outputSchemaBuilder.build();\n\n      PCollection<Row> result =\n          input\n              .get(INPUT_ROWS_TAG)\n              .apply(","sourceCodeStart":105,"sourceCodeEnd":141,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/schemas/transforms/providers/JavaExplodeTransformProvider.java#L105-L141","documentation":"JavaExplodeTransformProvider explodes array/iterable fields of a Row schema into separate rows. It throws this IllegalArgumentException when a field listed in the explode configuration is not an iterable (array/list) type, i.e. its schema type has no collection element type. The library requires every configured explode field to actually be a collection so each element can become its own row.","triggerScenarios":"Calling expand() on a PCollectionRowTuple where the input schema contains a field named in configuration.getFields() whose Schema.FieldType.getCollectionElementType() is null — e.g. configuring explode on a STRING, INT64, or MAP field instead of an ARRAY field.","commonSituations":"Misconfigured transform where the configured field list doesn't match the actual input schema; upstream schema changed a field from ARRAY<INT64> to INT64; typos causing the wrong field (a scalar one) to be matched.","solutions":["Check the input Row schema and ensure every field in the transform's 'fields' configuration is an ARRAY/iterable type","Remove scalar fields from the configured fields list","Fix the upstream pipeline so the field is actually a collection before this transform","Add a pre-flight schema validation step before expand()"],"exampleFix":"// before\nJavaExplodeTransformProvider.configure().setFields(Arrays.asList(\"tags\", \"name\")).create();\n// after\nJavaExplodeTransformProvider.configure().setFields(Arrays.asList(\"tags\")).create(); // only iterable fields","handlingStrategy":"validation","validationCode":"Schema schema = input.get(INPUT_ROWS_TAG).getSchema();\nfor (String name : configuration.getFields()) {\n  if (schema.getField(name).getType().getCollectionElementType() == null)\n    throw new IllegalArgumentException(\"Field is not iterable: \" + name);\n}","typeGuard":"boolean isIterableField(Schema.Field f) { return f.getType().getCollectionElementType() != null; }","tryCatchPattern":null,"preventionTips":["Validate configured field names against the input schema before expanding","Keep the explode config in sync with upstream schema changes"],"tags":["java","apache-beam","schema","configuration"],"backgroundTag":"invalid-argument-value","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"}