apache/beam · error · IllegalArgumentException

boolean cross product parameter required to explode more tha

Error message

boolean cross product parameter required to explode more than one field

What it means

When exploding multiple fields, the transform needs to know whether to produce the cross product of elements across fields or explode them independently. If the 'crossProduct' configuration option is null (unset) and more than one field is configured, this IllegalArgumentException is thrown because the semantics would be ambiguous.

Source

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

              .get(INPUT_ROWS_TAG)
              .apply(
                  "Explode",
                  ParDo.of(
                      createDoFn(
                          configuration.getFields(),
                          configuration.getCrossProduct(),
                          outputSchema)));
      result.setRowSchema(outputSchema);

      return PCollectionRowTuple.of(OUTPUT_ROWS_TAG, result);
    }

    private static DoFn<Row, Row> createDoFn(
        List<String> fields, Boolean crossProductObj, Schema outputSchema) {
      boolean crossProduct;
      if (crossProductObj == null) {
        if (fields.size() > 1) {
          throw new IllegalArgumentException(
              "boolean cross product parameter required to explode more than one field");
        }
        crossProduct = false;
      } else {
        crossProduct = crossProductObj;
      }
      int numFields = outputSchema.getFields().size();
      boolean[] toExplode =
          Booleans.toArray(
              IntStream.range(0, numFields)
                  .mapToObj(index -> fields.contains(outputSchema.getField(index).getName()))
                  .collect(Collectors.toList()));
      if (crossProduct) {
        return new DoFn<Row, Row>() {
          @ProcessElement
          public void processElement(@Element Row inputRow, OutputReceiver<Row> out) {
            emitCrossProduct(inputRow, 0, new Object[numFields], out);
          }

View on GitHub (pinned to 12126d8942)

Solutions

1. Explicitly set the crossProduct boolean (true or false) when exploding more than one field
2. Explode one field per transform instance if cross-product semantics are not needed
3. Default the config value in your pipeline configuration file

Example fix

// before
JavaExplodeTransformProvider.configure().setFields(Arrays.asList("a", "b")).create();
// after
JavaExplodeTransformProvider.configure().setFields(Arrays.asList("a", "b")).setCrossProduct(true).create();

if (fields != null && fields.size() > 1 && crossProduct == null)
  throw new IllegalArgumentException("crossProduct must be set when exploding multiple fields");

When it happens

Trigger: Constructing the transform with a fields list of size > 1 and crossProduct left as null; createDoFn is called during expand() with crossProductObj == null.

Common situations: Forgetting to set the crossProduct boolean when configuring explosion of 2+ fields; config deserialization that omits the optional boolean.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• No filesystem found for scheme
• Exploded field %s must be an iterable type, got %s.
• ${config}
• Unknown log level ${level}. Valid log levels are ${validLeve
• Unable to instantiate test options from system property %s:%

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