{"record":{"id":"a55d864fc8ef02c5","repo":"apache/beam","slug":"invalid-value-equalities-for-equalities-equality-should-be-a","errorCode":null,"errorMessage":"Invalid value \"{equalities}\" for \"equalities\". {equality} should be a dict[str, str] containing at least 2 items.","messagePattern":"Invalid value \"(.+?)\" for \"equalities\"\\. (.+?) should be a dict\\[str, str\\] containing at least 2 items\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/yaml/yaml_join.py","lineNumber":94,"sourceCode":"    equality = {pcoll_tag: equalities for pcoll_tag in pcolls}\n    return [equality]\n\n  if not isinstance(equalities, list):\n    raise ValueError(f'{error_prefix} It should be a str or a list.')\n\n  input_edge_list = []\n  for equality in equalities:\n    invalid_dict_error = ValueError(\n        f'{error_prefix} {equality} '\n        f'should be a dict[str, str] containing at least 2 items.')\n    if not isinstance(equality, dict):\n      raise invalid_dict_error\n    if len(equality) < 2:\n      raise invalid_dict_error\n\n    for pcoll_tag, col in equality.items():\n      if pcoll_tag not in pcolls:\n        raise ValueError(\n            f'{error_prefix} \"{pcoll_tag}\" is not a specified alias in \"input\"')\n      if col not in valid_cols[pcoll_tag]:\n        raise ValueError(\n            f'{error_prefix} \"{col}\" is not a valid field in \"{pcoll_tag}\".')\n\n    input_edge_list.append(tuple(equality.keys()))\n\n  if not _is_connected(input_edge_list, len(pcolls)):\n    raise ValueError(\n        f'{error_prefix} '\n        f'The provided equalities do not connect all of {list(pcolls.keys())}.')\n\n  return equalities\n\n\ndef _parse_fields(tables, fields):\n  error_prefix = f'Invalid value \"{fields}\" for \"fields\".'\n  if not isinstance(fields, dict):","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/yaml/yaml_join.py#L76-L112","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Provide at least two key-value pairs in each equalities dict, e.g. [{left: id, right: id}].","Ensure each key is a valid input alias and each value is a valid column in that input.","Validate the equalities structure programmatically before building the pipeline."],"exampleFix":"// before\npipeline:\n  type: Join\n  input:\n    left: read_a\n    right: read_b\n  equalities: [{left: id}]\n// after\npipeline:\n  type: Join\n  input:\n    left: read_a\n    right: read_b\n  equalities: [{left: id, right: id}]","handlingStrategy":"validation","validationCode":"def validate_equalities(equalities, inputs):\n    for eq in equalities:\n        assert isinstance(eq, dict), f'not a dict: {eq}'\n        assert len(eq) >= 2, f'needs >=2 items: {eq}'\n        assert all(isinstance(k, str) and isinstance(v, str) for k, v in eq.items())","typeGuard":"def is_valid_equality(eq):\n    return isinstance(eq, dict) and len(eq) >= 2 and all(isinstance(k, str) and isinstance(v, str) for k, v in eq.items())","tryCatchPattern":"try:\n    join = Join(equalities=equalities)\nexcept ValueError as e:\n    if 'should be a dict[str, str] containing at least 2 items' in str(e):\n        raise ConfigError('each equalities entry needs >=2 alias->column pairs') from e\n    raise","preventionTips":["Always give both sides of the join key in one equality dict","Lint YAML so equalities entries are mappings, not lists or scalars","Test the pipeline spec on a small sample before production"],"tags":["apache-beam","yaml","validation","join"],"backgroundTag":"invalid-argument-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"}