apache/beam · error · ValueError

Invalid value " " for "equalities". " " is not a specified…

Error message

Invalid value "{equalities}" for "equalities". "{pcoll_tag}" is not a specified alias in "input"

What it means

Within an equality dict, each key must be an input alias declared in the transform's 'input' mapping. _validate_equalities raises this error when a pcoll tag used as an equality key is not found among the specified aliases.

Solutions

Make each equality key exactly match an alias defined in the 'input' mapping.
Fix typos in alias names in equalities.
Update equalities whenever you rename inputs.

Example fix

// before
input: {left: read_a, right: read_b}
equalities: [{lft: id, right: id}]
// after
input: {left: read_a, right: read_b}
equalities: [{left: id, right: id}]

Defensive patterns

Strategy: validation

Validate before calling

def check_aliases(equalities, inputs):
    for eq in equalities:
        for tag in eq:
            if tag not in inputs:
                raise ValueError(f'alias {tag!r} not in input {list(inputs)}')

Try / catch

try:
    result = SqlJoinTransform(config)
except ValueError as e:
    if 'is not a specified alias' in str(e):
        raise ConfigError(f'equality key must match an input alias: {e}') from e
    raise

Prevention

Copy-paste alias names from the input block instead of retyping them
Grep the spec for each equality key to confirm it exists in input
Rename aliases and equalities together in one edit

When it happens

Trigger: Using a key like {lft: id, rgt: id} when the inputs are declared as {left: ..., right: ...}; renaming an input alias in 'input' without updating equalities; a typo in the alias name.

Common situations: Hand-edited YAML where the input alias was changed or misspelled; copying join conditions from a different pipeline with different alias names.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

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

Appendix: source

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

        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):
    raise ValueError(f'{error_prefix} Fields must be a dict.')
  output_fields = []
  named_columns = set()
  for input, cols in fields.items():
    if input not in tables:
      raise ValueError(f'An invalid input "{input}" was specified in "fields".')
    if isinstance(cols, list):
      for col in cols:
        if not isinstance(col, str):

View on GitHub (pinned to 12126d8942)