apache/beam · error · TypeError

Fields must be a mapping or iterable of strings, got {fields

Error message

Fields must be a mapping or iterable of strings, got {fields}

What it means

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).

Source

Thrown at sdks/python/apache_beam/yaml/yaml_mapping.py:949

        as a Java or Python object.
    * `pane_info`: A schema'd representation of the current pane info, including
        its index, whether it was the last firing, etc.

  As a convenience, a list rather than a mapping of fields may be provided,
  in which case the fields will be named according to the requested values.

  Args:
    fields: A mapping of new field names to various windowing parameters,
      as documented above.  If omitted, defaults to
      `[timestamp, window_start, window_end]`.
  """
  if fields is None:
    fields = ['timestamp', 'window_start', 'window_end']
  if not isinstance(fields, Mapping):
    if isinstance(fields, Iterable) and not isinstance(fields, str):
      fields = {fld: fld for fld in fields}
    else:
      raise TypeError(
          'Fields must be a mapping or iterable of strings, got {fields}')

  existing_fields = named_fields_from_element_type(pcoll.element_type)
  new_fields = []
  for field, value in fields.items():
    if value not in _WINDOWING_INFO_TYPES:
      raise ValueError(
          f'{value} is not a valid windowing parameter; '
          f'must be one of {list(_WINDOWING_INFO_TYPES.keys())}')
    elif field in existing_fields:
      raise ValueError(f'Input schema already has a field named {field}.')
    else:
      new_fields.append((field, _WINDOWING_INFO_TYPES[value]))

  def augment_row(
      row,
      timestamp=beam.DoFn.TimestampParam,
      window=beam.DoFn.WindowParam,

View on GitHub (pinned to 12126d8942)

Solutions

  1. Provide `fields` as a YAML list, e.g. fields: [timestamp, window_start, window_end].
  2. If mapping names, use a mapping of new_field_name -> windowing parameter instead of a scalar.
  3. Omit `fields` entirely to get the defaults (timestamp, window_start, window_end).

Example fix

# before
fields: timestamp
# after
fields: [timestamp, window_start, window_end]
Defensive patterns

Strategy: validation

Validate before calling

from collections.abc import Mapping, Iterable
if fields is not None and not isinstance(fields, (Mapping, list)) or isinstance(fields, str):
    raise ValueError('fields must be a list or mapping, not a scalar/string')

Type guard

def is_valid_fields(f):
    return f is None or (isinstance(f, Mapping) or (isinstance(f, Iterable) and not isinstance(f, str)))

Try / catch

try:
    augmented = extract_windowing_info(pc, fields=fields)
except TypeError as e:
    raise YamlConfigError('use fields: [timestamp, window_start, window_end]') from e

Prevention

When it happens

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

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

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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