{"record":{"id":"719aee16fc4281bd","repo":"apache/beam","slug":"cross-product-must-be-specified-true-or-false-when-exploding","errorCode":null,"errorMessage":"cross_product must be specified true or false when exploding multiple fields","messagePattern":"cross_product must be specified true or false when exploding multiple fields","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/yaml/yaml_mapping.py","lineNumber":575,"sourceCode":"          of the second field, etc. For example, the row\n          `(['a', 'b'], [1, 2])` would expand to the four rows\n          `('a', 1)`, `('a', 2)`, `('b', 1)`, and `('b', 2)` when\n          `cross_product` is set to `true` but only the two rows\n          `('a', 1)` and `('b', 2)` when it is set to `false`.\n          Only meaningful (and required) if multiple rows are specified.\n      error_handling: Whether and how to handle errors during iteration.\n  \"\"\"  # pylint: disable=line-too-long\n\n  def __init__(\n      self,\n      fields: Union[str, Collection[str]],\n      cross_product: Optional[bool] = None,\n      error_handling: Optional[Mapping[str, Any]] = None):\n    if isinstance(fields, str):\n      fields = [fields]\n    if cross_product is None:\n      if len(fields) > 1:\n        raise ValueError(\n            'cross_product must be specified true or false '\n            'when exploding multiple fields')\n      else:\n        # Doesn't matter.\n        cross_product = True\n    self._fields = fields\n    self._cross_product = cross_product\n    # TODO(yaml):\n    # 1. Support standard error handling argument.\n    # 2. Supposedly error_handling parameter is not an accepted parameter when\n    #    executing.  Needs further investigation.\n    self._exception_handling_args = exception_handling_args(error_handling)\n\n  @maybe_with_exception_handling\n  def expand(self, pcoll):\n    all_fields = [\n        x for x, _ in named_fields_from_element_type(pcoll.element_type)\n    ]","sourceCodeStart":557,"sourceCodeEnd":593,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/yaml/yaml_mapping.py#L557-L593","documentation":"The _Explode transform (FlatMap in YAML) accepts an optional `cross_product` flag that is only meaningful when exploding more than one field. If multiple fields are given and cross_product is not explicitly set to true or false, __init__ raises this ValueError because the combination semantics would be ambiguous.","triggerScenarios":"Configuring `fields: [a, b]` (a list of two or more iterable fields) in a FlatMap/Explode transform without specifying `cross_product: true|false`.","commonSituations":"Adding a second field to an existing single-field explode config that never needed cross_product before, copy-pasting examples, or passing fields as an already-multi-element list programmatically with cross_product left None.","solutions":["Add `cross_product: true` to produce all combinations, or `cross_product: false` to zip fields element-wise.","If you only need one field exploded, remove the extra field names from `fields`.","Pass an explicit boolean programmatically (cross_product=True/False) when constructing _Explode in code."],"exampleFix":"# before\n- type: FlatMap\n  config:\n    fields: [tags, scores]\n# after\n- type: FlatMap\n  config:\n    fields: [tags, scores]\n    cross_product: true","handlingStrategy":"validation","validationCode":"fields = [fields] if isinstance(fields, str) else fields\nif len(fields) > 1:\n    assert cross_product in (True, False), 'cross_product required for multiple fields'","typeGuard":"def explode_config_ok(cfg: dict) -> bool:\n    f = cfg.get('fields')\n    f = [f] if isinstance(f, str) else (f or [])\n    return len(f) <= 1 or isinstance(cfg.get('cross_product'), bool)","tryCatchPattern":"try:\n    out = pcoll | _Explode(fields=fields, cross_product=cross_product)\nexcept ValueError as e:\n    if 'cross_product must be specified' in str(e):\n        out = pcoll | _Explode(fields=fields, cross_product=True)\n    else:\n        raise","preventionTips":["Always set cross_product explicitly when exploding two or more fields","Decide between cross-product and zip semantics before configuring FlatMap","Validate YAML transform configs in CI before running pipelines"],"tags":["yaml","beam-yaml","config","flatmap"],"backgroundTag":"missing-required-config-field","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"}