apache/beam · error · ValueError

f'Unknown parameters {spec.keys()}'

Error message

f'Unknown parameters {spec.keys()}'

What it means

Raised by YamlProviders.WindowInto after selecting a window function: leftover keys in the spec dict indicate parameters that are not valid for the chosen window type. The transform validates that only recognized parameters were provided.

Source

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

      elif window_type == 'fixed':
        window_fn = window.FixedWindows(
            YamlProviders.WindowInto._parse_duration(spec.pop('size'), 'size'),
            YamlProviders.WindowInto._parse_duration(
                spec.pop('offset', 0), 'offset'))
      elif window_type == 'sliding':
        window_fn = window.SlidingWindows(
            YamlProviders.WindowInto._parse_duration(spec.pop('size'), 'size'),
            YamlProviders.WindowInto._parse_duration(
                spec.pop('period'), 'period'),
            YamlProviders.WindowInto._parse_duration(
                spec.pop('offset', 0), 'offset'))
      elif window_type == 'sessions':
        window_fn = window.Sessions(
            YamlProviders.WindowInto._parse_duration(spec.pop('gap'), 'gap'))
      else:
        raise ValueError(f'Unknown window type {window_type}')
      if spec:
        raise ValueError(f'Unknown parameters {spec.keys()}')
      # TODO: Triggering, etc.
      return beam.WindowInto(window_fn)

  @staticmethod
  @beam.ptransform_fn
  @maybe_with_exception_handling_transform_fn
  def log_for_testing(
      pcoll, *, level: Optional[str] = 'INFO', prefix: Optional[str] = ''):
    """Logs each element of its input PCollection.

    The output of this transform is a copy of its input for ease of use in
    chain-style pipelines.

    Args:
      level: one of ERROR, INFO, or DEBUG, mapped to a corresponding
        language-specific logging level
      prefix: an optional identifier that will get prepended to the element
        being logged

View on GitHub (pinned to 12126d8942)

Solutions

1. Remove parameters not valid for the chosen type: fixed uses size (+offset/period as supported), sliding uses size/period/offset, sessions uses only gap.
2. Fix key typos to match the exact expected parameter names.
3. Remove triggering/lateness options — they are not yet implemented for this YAML transform.

Example fix

# before
config:
  type: fixed
  size: 10m
  gap: 5m
# after
config:
  type: fixed
  size: 10m

ALLOWED = {'fixed': {'size','offset','period'}, 'sliding': {'size','period','offset'}, 'sessions': {'gap'}}
def validate_window_spec(spec):
    t = spec.get('type')
    extra = set(spec) - ALLOWED.get(t, set()) - {'type'}
    if extra:
        raise ValueError(f'Unknown parameters for {t}: {extra}')

try:
    transform = YamlProviders.WindowInto(spec)
except ValueError as e:
    if str(e).startswith('Unknown parameters'):
        logging.error('Remove/fix these window params: %s', e)
        raise
    raise

When it happens

Trigger: Passing e.g. 'gap' to a fixed window, 'size' to a sessions window, unknown keys like 'trigger' or 'every', or misspelling a valid key ('offest' instead of 'offset') for the given window type.

Common situations: Config copied between window types (fixed vs sliding vs sessions have different parameters), or attempts to configure triggering/allowed lateness which is not yet supported by this YAML transform.

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

• Unknown enrichment source: {enrichment_handler}
• "Cannot specify 'callable' with 'path' and 'name' for functi
• Missing type parameter for transform at {identify_object(spe
• error_handling config is not supported directly in the outpu
• Chain at {identify_object(spec)} missing transforms property

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