{"record":{"id":"92c6d1609a8e6b42","repo":"apache/beam","slug":"invalid-value-equalities-for-equalities-when-equalities-is-a","errorCode":null,"errorMessage":"Invalid value \"{equalities}\" for \"equalities\". When \"equalities\" is a str, it must be a field name that exists in all the specified inputs.","messagePattern":"Invalid value \"(.+?)\" for \"equalities\"\\. When \"equalities\" is a str, it must be a field name that exists in all the specified inputs\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/yaml/yaml_join.py","lineNumber":73,"sourceCode":"        f'{error_prefix} When specifying the value for type as a str, '\n        f'it must be one of the following: \"inner\", \"outer\", \"left\", \"right\"')\n\n\ndef _validate_equalities(equalities, pcolls):\n  error_prefix = f'Invalid value \"{equalities}\" for \"equalities\".'\n\n  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","sourceCodeStart":55,"sourceCodeEnd":91,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/yaml/yaml_join.py#L55-L91","documentation":"Thrown by _validate_equalities in apache_beam/yaml/yaml_join.py when 'equalities' is given as a str but that field name does not exist in the schema of at least one of the specified inputs. A shorthand equality string must be a shared join key across all inputs.","triggerScenarios":"equalities: id when one input's schema lacks an 'id' field (e.g. it is named 'user_id'); field renames upstream; case-sensitive mismatch.","commonSituations":"Joining tables from different sources with inconsistent column names; forgetting to rename/alias fields before the join.","solutions":["Use the dict/list form of equalities to map per-input field names: equalities: [{input1: id, input2: user_id}].","Rename the field with a Map/SQL projection so all inputs share the key name.","Inspect pcoll.element_type._fields for each input to confirm exact field names."],"exampleFix":"// before\nequalities: id  # input2 has 'user_id'\n// after\nequalities:\n  - input1: id\n    input2: user_id","handlingStrategy":"validation","validationCode":"if isinstance(eq, str):\n    for tag, pc in inputs.items():\n        if eq not in getattr(pc.element_type, '_fields', []):\n            raise ValueError(f'field {eq!r} missing from input {tag}')","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Only use the string shorthand when all inputs share the key field name","Prefer the per-input dict form of equalities for heterogeneous schemas","Inspect element_type._fields of every input before configuring the join"],"tags":["apache-beam","yaml","join","schema"],"backgroundTag":"schema-validation-failed","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"}