{"record":{"id":"aab9eac3112e36f8","repo":"apache/beam","slug":"fields-must-be-a-mapping-or-iterable-of-strings-got-fields","errorCode":null,"errorMessage":"Fields must be a mapping or iterable of strings, got {fields}","messagePattern":"Fields must be a mapping or iterable of strings, got (.+?)","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/yaml/yaml_mapping.py","lineNumber":949,"sourceCode":"        as a Java or Python object.\n    * `pane_info`: A schema'd representation of the current pane info, including\n        its index, whether it was the last firing, etc.\n\n  As a convenience, a list rather than a mapping of fields may be provided,\n  in which case the fields will be named according to the requested values.\n\n  Args:\n    fields: A mapping of new field names to various windowing parameters,\n      as documented above.  If omitted, defaults to\n      `[timestamp, window_start, window_end]`.\n  \"\"\"\n  if fields is None:\n    fields = ['timestamp', 'window_start', 'window_end']\n  if not isinstance(fields, Mapping):\n    if isinstance(fields, Iterable) and not isinstance(fields, str):\n      fields = {fld: fld for fld in fields}\n    else:\n      raise TypeError(\n          'Fields must be a mapping or iterable of strings, got {fields}')\n\n  existing_fields = named_fields_from_element_type(pcoll.element_type)\n  new_fields = []\n  for field, value in fields.items():\n    if value not in _WINDOWING_INFO_TYPES:\n      raise ValueError(\n          f'{value} is not a valid windowing parameter; '\n          f'must be one of {list(_WINDOWING_INFO_TYPES.keys())}')\n    elif field in existing_fields:\n      raise ValueError(f'Input schema already has a field named {field}.')\n    else:\n      new_fields.append((field, _WINDOWING_INFO_TYPES[value]))\n\n  def augment_row(\n      row,\n      timestamp=beam.DoFn.TimestampParam,\n      window=beam.DoFn.WindowParam,","sourceCodeStart":931,"sourceCodeEnd":967,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/yaml/yaml_mapping.py#L931-L967","documentation":"Beam YAML's `_ExtractWindowingInfo` accepts a `fields` argument that must be either a Mapping (field name -> windowing parameter) or an iterable of strings, but not a scalar/other type. yaml_mapping.py:949 raises TypeError when `fields` is neither (e.g. a single string or a number).","triggerScenarios":"Passing `fields` as a bare string like fields: timestamp in YAML (a string IS iterable, but the code explicitly excludes str), or as a non-iterable value such as an int or bool.","commonSituations":"YAML config where `fields:` is given one value instead of a list; users copying a field name without wrapping it in a list; quoting mistakes that collapse a list into a scalar.","solutions":["Provide `fields` as a YAML list, e.g. fields: [timestamp, window_start, window_end].","If mapping names, use a mapping of new_field_name -> windowing parameter instead of a scalar.","Omit `fields` entirely to get the defaults (timestamp, window_start, window_end)."],"exampleFix":"# before\nfields: timestamp\n# after\nfields: [timestamp, window_start, window_end]","handlingStrategy":"validation","validationCode":"from collections.abc import Mapping, Iterable\nif fields is not None and not isinstance(fields, (Mapping, list)) or isinstance(fields, str):\n    raise ValueError('fields must be a list or mapping, not a scalar/string')","typeGuard":"def is_valid_fields(f):\n    return f is None or (isinstance(f, Mapping) or (isinstance(f, Iterable) and not isinstance(f, str)))","tryCatchPattern":"try:\n    augmented = extract_windowing_info(pc, fields=fields)\nexcept TypeError as e:\n    raise YamlConfigError('use fields: [timestamp, window_start, window_end]') from e","preventionTips":["Always write fields as a YAML list, never a bare scalar.","Omit fields to accept defaults.","Lint YAML transforms to catch scalar-valued list options."],"tags":["python","apache-beam","yaml","argument-type"],"backgroundTag":"invalid-argument-format","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"}