{"record":{"id":"868b576052b7d94f","repo":"apache/beam","slug":"windowing-config-string-must-be-a-yaml-json-map","errorCode":null,"errorMessage":"Windowing config string must be a YAML/JSON map.","messagePattern":"Windowing config string must be a YAML/JSON map\\.","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/yaml/yaml_transform.py","lineNumber":1115,"sourceCode":"  return spec\n\n\ndef preprocess_windowing(spec):\n  if spec['type'] == 'WindowInto':\n    # This is the transform where it is actually applied.\n    if 'windowing' in spec:\n      spec['config'] = spec.get('config', {})\n      spec['config']['windowing'] = spec.pop('windowing')\n\n    if spec.get('config', {}).get('windowing'):\n      windowing_config = spec['config']['windowing']\n      if isinstance(windowing_config, str):\n        try:\n          # PyYAML can load a JSON string - one-line and multi-line.\n          # Without this code, multi-line is not supported.\n          parsed_config = yaml.safe_load(windowing_config)\n          if not isinstance(parsed_config, dict):\n            raise TypeError('Windowing config string must be a YAML/JSON map.')\n          spec['config']['windowing'] = parsed_config\n        except Exception as e:\n          raise ValueError(\n              f'Error parsing windowing config string at \\\n                {identify_object(spec)}: {e}') from e\n    return spec\n  elif 'windowing' not in spec:\n    # Nothing to do.\n    return spec\n\n  if spec['type'] == 'composite':\n    # Apply the windowing to any reads, creates, etc. in this transform\n    # TODO(robertwb): Better handle the case where a read is followed by a\n    # setting of the timestamps. We should be careful of sliding windows\n    # in particular.\n    spec = push_windowing_to_roots(spec)\n\n  windowing = spec.pop('windowing')","sourceCodeStart":1097,"sourceCodeEnd":1133,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/yaml/yaml_transform.py#L1097-L1133","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Make the string a valid YAML/JSON map, e.g. '{\"type\": \"fixed\", \"size\": \"10s\"}'.","Better, use a native YAML mapping for windowing instead of a string.","Check the nested error message (the ValueError includes the underlying e) to see exactly why parsing/typing failed."],"exampleFix":"# before\nconfig:\n  windowing: '10 seconds'\n# after\nconfig:\n  windowing:\n    type: fixed\n    size: 10s","handlingStrategy":"validation","validationCode":"w = spec.get('config', {}).get('windowing')\nif isinstance(w, str):\n    import yaml\n    parsed = yaml.safe_load(w)\n    if not isinstance(parsed, dict):\n        raise ValueError('windowing string must parse to a mapping')","typeGuard":"def is_windowing_map(w):\n    if isinstance(w, dict):\n        return True\n    if isinstance(w, str):\n        import yaml\n        return isinstance(yaml.safe_load(w), dict)\n    return False","tryCatchPattern":"try:\n    spec = preprocess_windowing(spec)\nexcept ValueError as e:\n    if 'windowing' in str(e):\n        spec['config']['windowing'] = {'type': 'fixed', 'size': '10s'}\n    else:\n        raise","preventionTips":["Prefer native YAML mappings for windowing over strings","Test windowing strings with yaml.safe_load locally","Never use bare scalars or lists as windowing configs"],"tags":["python","apache-beam","yaml","windowing","validation"],"backgroundTag":"invalid-config-value","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"}