apache/beam · error · TypeError

Windowing config string must be a YAML/JSON map.

Error message

Windowing config string must be a YAML/JSON map.

What it means

preprocess_windowing allows config.windowing to be given as a string containing YAML/JSON, which is parsed with yaml.safe_load. If the string parses to something other than a dict (e.g. a scalar like '5' or a list), the code raises TypeError, which is then re-raised as a ValueError — windowing must be a mapping of windowing parameters.

Solutions

1. Make the string a valid YAML/JSON map, e.g. '{"type": "fixed", "size": "10s"}'.
2. Better, use a native YAML mapping for windowing instead of a string.
3. Check the nested error message (the ValueError includes the underlying e) to see exactly why parsing/typing failed.

Example fix

# before
config:
  windowing: '10 seconds'
# after
config:
  windowing:
    type: fixed
    size: 10s

w = spec.get('config', {}).get('windowing')
if isinstance(w, str):
    import yaml
    parsed = yaml.safe_load(w)
    if not isinstance(parsed, dict):
        raise ValueError('windowing string must parse to a mapping')

def is_windowing_map(w):
    if isinstance(w, dict):
        return True
    if isinstance(w, str):
        import yaml
        return isinstance(yaml.safe_load(w), dict)
    return False

try:
    spec = preprocess_windowing(spec)
except ValueError as e:
    if 'windowing' in str(e):
        spec['config']['windowing'] = {'type': 'fixed', 'size': '10s'}
    else:
        raise

When it happens

Trigger: preprocess_windowing encountering spec.config.windowing as a string whose yaml.safe_load result is not a dict — e.g. windowing: '10 seconds' (parses to a string) or a JSON array string.

Common situations: Writing a human-friendly windowing shorthand like 'fixed-10s' instead of a mapping; JSON with wrong nesting so the top level is a list; YAML scalar collapsing (value quoted incorrectly).

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Edge source and target cannot be empty
• Error parsing windowing config string at
• f"Invalid windowing value ' '. Must provide numeric value.
• f'Unknown window type
• HuggingFacePipelineModelHandler requires either 'task' or…

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

Appendix: source

Thrown at sdks/python/apache_beam/yaml/yaml_transform.py:1115

  return spec


def preprocess_windowing(spec):
  if spec['type'] == 'WindowInto':
    # This is the transform where it is actually applied.
    if 'windowing' in spec:
      spec['config'] = spec.get('config', {})
      spec['config']['windowing'] = spec.pop('windowing')

    if spec.get('config', {}).get('windowing'):
      windowing_config = spec['config']['windowing']
      if isinstance(windowing_config, str):
        try:
          # PyYAML can load a JSON string - one-line and multi-line.
          # Without this code, multi-line is not supported.
          parsed_config = yaml.safe_load(windowing_config)
          if not isinstance(parsed_config, dict):
            raise TypeError('Windowing config string must be a YAML/JSON map.')
          spec['config']['windowing'] = parsed_config
        except Exception as e:
          raise ValueError(
              f'Error parsing windowing config string at \
                {identify_object(spec)}: {e}') from e
    return spec
  elif 'windowing' not in spec:
    # Nothing to do.
    return spec

  if spec['type'] == 'composite':
    # Apply the windowing to any reads, creates, etc. in this transform
    # TODO(robertwb): Better handle the case where a read is followed by a
    # setting of the timestamps. We should be careful of sliding windows
    # in particular.
    spec = push_windowing_to_roots(spec)

  windowing = spec.pop('windowing')

View on GitHub (pinned to 12126d8942)