apache/beam · error · ValueError

is not a valid windowing parameter; must be one of

Error message

{value} is not a valid windowing parameter; must be one of {list(_WINDOWING_INFO_TYPES.keys())}

What it means

`_ExtractWindowingInfo` only allows a fixed set of windowing parameters (keys of `_WINDOWING_INFO_TYPES`, e.g. timestamp, window_start, window_end). yaml_mapping.py:956 raises ValueError when a requested value is not one of these valid parameters.

Solutions

1. Use only the supported values: timestamp, window_start, window_end (per _WINDOWING_INFO_TYPES).
2. Check the error message's 'must be one of' list and correct the spelling/casing.
3. Map a custom output field name to a valid parameter, e.g. {my_ts: timestamp}.

Example fix

# before
fields: {ts: time, ws: window_start}
# after
fields: {ts: timestamp, ws: window_start}

VALID = {'timestamp', 'window_start', 'window_end'}
bad = [v for v in fields.values()] if isinstance(fields, Mapping) else fields
invalid = [v for v in (bad or []) if v not in VALID]
assert not invalid, f'invalid windowing params: {invalid}'

def is_windowing_param(v):
    return v in ('timestamp', 'window_start', 'window_end')

try:
    pc = extract_windowing_info(pc, fields=fields)
except ValueError as e:
    raise YamlConfigError(str(e)) from e

When it happens

Trigger: A `fields` mapping/entry references a value like 'window' or 'end' that is not a key in _WINDOWING_INFO_TYPES.

Common situations: Guessing parameter names ('window_end' vs 'end'); copying field names from other frameworks; misspelling a valid parameter.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• At most one of --create_test and --fix_tests may be…
• Cannot convert element of type
• "Cannot specify 'callable' with 'path' and 'name' for…
• Chain at missing transforms property.
• Dependencies must be a list of strings, got

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

Appendix: source

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

  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,
      pane_info=beam.DoFn.PaneInfoParam):
    as_dict = row._asdict()
    for field, value in fields.items():
      as_dict[field] = _WINDOWING_INFO_EXTRACTORS[value](locals())
    return beam.Row(**as_dict)

  return pcoll | beam.Map(augment_row).with_output_types(

View on GitHub (pinned to 12126d8942)