{"record":{"id":"7cb56df7a5e2fd43","repo":"apache/beam","slug":"invalid-value-equalities-for-equalities-it-should-be-a-str","errorCode":null,"errorMessage":"Invalid value \"{equalities}\" for \"equalities\". It should be a str or a list.","messagePattern":"Invalid value \"(.+?)\" for \"equalities\"\\. It should be a str or a list\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/yaml/yaml_join.py","lineNumber":80,"sourceCode":"  valid_cols = {\n      name: set(\n          dict(fields).keys() if fields and all(\n              isinstance(field, tuple) for field in fields) else fields)\n      for (name, pcoll) in pcolls.items()\n      for fields in [getattr(pcoll.element_type, '_fields', [])]\n  }\n\n  if isinstance(equalities, str):\n    for cols in valid_cols.values():\n      if equalities not in cols:\n        raise ValueError(\n            f'{error_prefix} When \"equalities\" is a str, '\n            f'it must be a field name that exists in all the specified inputs.')\n    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}\".')","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/yaml/yaml_join.py#L62-L98","documentation":"Thrown by _validate_equalities in apache_beam/yaml/yaml_join.py when the 'equalities' parameter is neither a str (a shared field name) nor a list (list of per-equality dicts). Any other type is rejected.","triggerScenarios":"equalities: given as a dict directly ({input1: id, input2: id}) instead of wrapped in a list; equalities given as a number or null.","commonSituations":"YAML authors writing the mapping form without the outer list; programmatic callers passing a single dict.","solutions":["Wrap the mapping in a list: equalities: [{input1: id, input2: id}].","Or use the plain string shorthand when the field name is identical in all inputs.","Validate the value is str or list of dicts before invoking the transform."],"exampleFix":"// before\nequalities: {input1: id, input2: id}\n// after\nequalities:\n  - input1: id\n    input2: id","handlingStrategy":"validation","validationCode":"if not (isinstance(eq, str) or isinstance(eq, list)):\n    raise TypeError(\"'equalities' must be a str or a list of dicts\")","typeGuard":"def is_valid_equalities(eq):\n    return isinstance(eq, str) or (isinstance(eq, list) and all(isinstance(e, dict) for e in eq))","tryCatchPattern":null,"preventionTips":["Remember the dict form must be wrapped in a list","Use the plain string shorthand when all inputs share the key","Validate the transform config against the Join schema before running"],"tags":["apache-beam","yaml","join","validation"],"backgroundTag":"invalid-argument-format","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"}