apache/beam · error · ValueError

Invalid value " " for "equalities". should be a dict[str…

Error message

Invalid value "{equalities}" for "equalities". {equality} should be a dict[str, str] containing at least 2 items.

What it means

This error comes from the Beam YAML SQL Join transform's equality validation (_validate_equalities). Each entry in the 'equalities' list must be a dict mapping at least 2 input aliases to column names (a pair-wise join condition). If a dict has fewer than 2 items (or is not a dict of str->str at all), the invalid_dict_error is raised with this message.

Solutions

  1. Provide at least two key-value pairs in each equalities dict, e.g. [{left: id, right: id}].
  2. Ensure each key is a valid input alias and each value is a valid column in that input.
  3. Validate the equalities structure programmatically before building the pipeline.

Example fix

// before
pipeline:
  type: Join
  input:
    left: read_a
    right: read_b
  equalities: [{left: id}]
// after
pipeline:
  type: Join
  input:
    left: read_a
    right: read_b
  equalities: [{left: id, right: id}]
Defensive patterns

Strategy: validation

Validate before calling

def validate_equalities(equalities, inputs):
    for eq in equalities:
        assert isinstance(eq, dict), f'not a dict: {eq}'
        assert len(eq) >= 2, f'needs >=2 items: {eq}'
        assert all(isinstance(k, str) and isinstance(v, str) for k, v in eq.items())

Type guard

def is_valid_equality(eq):
    return isinstance(eq, dict) and len(eq) >= 2 and all(isinstance(k, str) and isinstance(v, str) for k, v in eq.items())

Try / catch

try:
    join = Join(equalities=equalities)
except ValueError as e:
    if 'should be a dict[str, str] containing at least 2 items' in str(e):
        raise ConfigError('each equalities entry needs >=2 alias->column pairs') from e
    raise

Prevention

When it happens

Trigger: Passing an equalities entry with fewer than 2 keys, e.g. equalities: [[{left: id}]] with only one mapping, an empty dict {}, or a non-dict entry like a plain string or single-element list.

Common situations: Users writing a self-join or multi-input join config by hand and specifying only one side of the join key; YAML that collapses a two-key mapping into one; copying an outer/equi-join example and deleting a column.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

Thrown at sdks/python/apache_beam/yaml/yaml_join.py:94

    equality = {pcoll_tag: equalities for pcoll_tag in pcolls}
    return [equality]

  if not isinstance(equalities, list):
    raise ValueError(f'{error_prefix} It should be a str or a list.')

  input_edge_list = []
  for equality in equalities:
    invalid_dict_error = ValueError(
        f'{error_prefix} {equality} '
        f'should be a dict[str, str] containing at least 2 items.')
    if not isinstance(equality, dict):
      raise invalid_dict_error
    if len(equality) < 2:
      raise invalid_dict_error

    for pcoll_tag, col in equality.items():
      if pcoll_tag not in pcolls:
        raise ValueError(
            f'{error_prefix} "{pcoll_tag}" is not a specified alias in "input"')
      if col not in valid_cols[pcoll_tag]:
        raise ValueError(
            f'{error_prefix} "{col}" is not a valid field in "{pcoll_tag}".')

    input_edge_list.append(tuple(equality.keys()))

  if not _is_connected(input_edge_list, len(pcolls)):
    raise ValueError(
        f'{error_prefix} '
        f'The provided equalities do not connect all of {list(pcolls.keys())}.')

  return equalities


def _parse_fields(tables, fields):
  error_prefix = f'Invalid value "{fields}" for "fields".'
  if not isinstance(fields, dict):

View on GitHub (pinned to 12126d8942)