apache/beam · error · ValueError

f"Invalid windowing value ' '. Must provide numeric value.

Error message

f"Invalid windowing {name} value '{suffix if not value else value}'. Must provide numeric value."

What it means

Raised by YamlProviders.WindowInto._parse_duration in apache_beam yaml_provider.py when a windowing duration/offset parameter has no numeric part after stripping the optional time-unit suffix. The regex '^(.*?)([^\d]*)$' splits the value into digits and a suffix; if the numeric part is empty, no usable duration was provided.

Solutions

1. Provide a numeric value, optionally with a time-unit suffix, e.g. 'gap: 5m' or 'gap: 300s'.
2. If the value comes from a parameter/options substitution, verify it resolves to a numeric string before the pipeline runs.
3. Default the value in the YAML or calling code, e.g. use a coalesce/default so an empty value becomes '60s'.

Example fix

# before
gap: minutes
# after
gap: 10m

def validate_windowing_value(value):
    m = re.match(r'^(.*?)([^\d]*)$', str(value))
    if not m or not m.group(1):
        raise ValueError(f'Windowing value {value!r} must include a numeric value, e.g. "5m"')

def is_valid_duration_str(v):
    return bool(re.fullmatch(r'\s*\d+(\.\d+)?\s*[smhd]?\s*', str(v)))

try:
    result = beam.WindowInto(window.Sessions(gap))
except ValueError as e:
    if 'Invalid windowing' in str(e):
        logging.error('Bad windowing config: %s', e)
        gap = '60s'  # fallback default
    else:
        raise

When it happens

Trigger: Calling WindowInto (via YAML 'Assign windows to elements based on their timestamp' transform) with a duration, gap, or offset parameter whose value is a non-numeric string such as 'sec', 'minutes', '' (empty string), or a value whose digits were all consumed by the suffix regex.

Common situations: YAML pipeline authors write 'gap: minutes' instead of 'gap: 5m' or 'gap: 300s', omit the number entirely, or pass a config-substituted placeholder that resolves to a unit-only string.

Understand the failure class

Background: "invalid duration" / "failed to parse duration": why your timeout, interval, or TTL string is rejected and which formats each library accepts — this error's family across 32 libraries.

Related errors

• Error parsing windowing config string at
• f'Unknown window type
• "Invalid windowing time unit ' '. Valid time units are .
• Windowing config string must be a YAML/JSON map.
• accumulation_mode must be provided for non-trivial triggers

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

Appendix: source

Thrown at sdks/python/apache_beam/yaml/yaml_provider.py:1130

      windowing: the type and parameters of the windowing to perform
    """
    def __init__(self, windowing):
      self._window_transform = self._parse_window_spec(windowing)

    def expand(self, pcoll):
      return pcoll | self._window_transform

    @staticmethod
    def _parse_duration(value, name):
      time_units = {
          'ms': 0.001, 's': 1, 'm': 60, 'h': 60 * 60, 'd': 60 * 60 * 12
      }
      value, suffix = re.match(r'^(.*?)([^\d]*)$', str(value)).groups()
      # Default to seconds if time unit suffix is not defined
      if not suffix:
        suffix = 's'
      if not value:
        raise ValueError(
            f"Invalid windowing {name} value "
            f"'{suffix if not value else value}'. "
            f"Must provide numeric value.")
      if suffix not in time_units:
        raise ValueError((
            "Invalid windowing {} time unit '{}'. " +
            "Valid time units are {}.").format(
                name,
                suffix,
                ', '.join("'{}'".format(k) for k in time_units.keys())))
      return float(value) * time_units[suffix]

    @staticmethod
    def _parse_window_spec(spec):
      spec = dict(spec)
      window_type = spec.pop('type')
      # TODO: These are in seconds, perhaps parse duration strings meaningfully?
      if window_type == 'global':

View on GitHub (pinned to 12126d8942)