apache/beam · error · IllegalArgumentException

Exploded field %s must be an iterable type, got %s.

Error message

Exploded field %s must be an iterable type, got %s.

What it means

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.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/schemas/transforms/providers/JavaExplodeTransformProvider.java:123

  }

  /** A {@link SchemaTransform} for Explode. */
  protected static class ExplodeTransform extends SchemaTransform {

    private final Configuration configuration;

    ExplodeTransform(Configuration configuration) {
      this.configuration = configuration;
    }

    @Override
    public PCollectionRowTuple expand(PCollectionRowTuple input) {
      Schema inputSchema = input.get(INPUT_ROWS_TAG).getSchema();
      Schema.Builder outputSchemaBuilder = new Schema.Builder();
      for (Schema.Field field : inputSchema.getFields()) {
        if (configuration.getFields().contains(field.getName())) {
          if (field.getType().getCollectionElementType() == null) {
            throw new IllegalArgumentException(
                String.format(
                    "Exploded field %s must be an iterable type, got %s.",
                    field.getName(), field.getType()));
          } else {
            outputSchemaBuilder =
                outputSchemaBuilder.addField(
                    field.getName(), field.getType().getCollectionElementType());
          }
        } else {
          outputSchemaBuilder = outputSchemaBuilder.addField(field);
        }
      }
      Schema outputSchema = outputSchemaBuilder.build();

      PCollection<Row> result =
          input
              .get(INPUT_ROWS_TAG)
              .apply(

View on GitHub (pinned to 12126d8942)

Solutions

1. Check the input Row schema and ensure every field in the transform's 'fields' configuration is an ARRAY/iterable type
2. Remove scalar fields from the configured fields list
3. Fix the upstream pipeline so the field is actually a collection before this transform
4. Add a pre-flight schema validation step before expand()

Example fix

// before
JavaExplodeTransformProvider.configure().setFields(Arrays.asList("tags", "name")).create();
// after
JavaExplodeTransformProvider.configure().setFields(Arrays.asList("tags")).create(); // only iterable fields

Schema schema = input.get(INPUT_ROWS_TAG).getSchema();
for (String name : configuration.getFields()) {
  if (schema.getField(name).getType().getCollectionElementType() == null)
    throw new IllegalArgumentException("Field is not iterable: " + name);
}

boolean isIterableField(Schema.Field f) { return f.getType().getCollectionElementType() != null; }

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Configuration schema provided does not match expected
• Cannot provide a coder for a Beam Row. Please provide a sche
• No filesystem found for scheme
• Failed to decode Schema due to an error decoding Field proto
• Encountered UNSPECIFIED AtomicType

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/8f75634e88eba9b4. Report an issue: GitHub.