{"record":{"id":"10c57a6fa52d3bc1","repo":"apache/beam","slug":"unable-to-deterministically-order-keys-of-dict-for-s","errorCode":null,"errorMessage":"Unable to deterministically order keys of dict for '%s'","messagePattern":"Unable to deterministically order keys of dict for '(.+?)'","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/coders/coder_impl.py","lineNumber":455,"sourceCode":"      stream.write_byte(LIST_TYPE if t is list else TUPLE_TYPE)\n      stream.write_var_int64(len(value))\n      for e in value:\n        self.encode_to_stream(e, stream, True)\n    elif t is bool:\n      stream.write_byte(BOOL_TYPE)\n      stream.write_byte(value)\n    elif t in _ITERABLE_LIKE_TYPES:\n      stream.write_byte(ITERABLE_LIKE_TYPE)\n      self.iterable_coder_impl.encode_to_stream(value, stream, nested)\n    elif t is dict:\n      dict_value = value  # for typing\n      stream.write_byte(DICT_TYPE)\n      stream.write_var_int64(len(dict_value))\n      if self.requires_deterministic_step_label is not None:\n        try:\n          ordered_kvs = sorted(dict_value.items())\n        except Exception as exn:\n          raise TypeError(\n              \"Unable to deterministically order keys of dict for '%s'\" %\n              self.requires_deterministic_step_label) from exn\n        for k, v in ordered_kvs:\n          self.encode_to_stream(k, stream, True)\n          self.encode_to_stream(v, stream, True)\n      else:\n        # Loop over dict.items() is optimized by Cython.\n        for k, v in dict_value.items():\n          self.encode_to_stream(k, stream, True)\n          self.encode_to_stream(v, stream, True)\n    elif t is set:\n      stream.write_byte(SET_TYPE)\n      stream.write_var_int64(len(value))\n      if self.requires_deterministic_step_label is not None:\n        try:\n          value = sorted(value)\n        except Exception as exn:\n          raise TypeError(","sourceCodeStart":437,"sourceCodeEnd":473,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/coders/coder_impl.py#L437-L473","documentation":"When a dict coder requires deterministic encoding (requires_deterministic_step_label set), encode_to_stream sorts the dict items before writing. If the keys cannot be compared/sorted (mixed or unorderable key types), it raises TypeError naming the step label, chained from the original exception.","triggerScenarios":"Encoding a PCollection containing dicts with heterogeneous or unorderable keys (e.g. {1: 'a', 'b': 2} or keys containing None) under a deterministic-coding requirement (side inputs, GBK keys, deterministic output requirement).","commonSituations":"Dictionaries with mixed int/str keys built from JSON-ish data; keys that are None; sets/dicts flowing into stages where Beam enforces determinism for correctness (stateful DoFns, cross-language, streaming).","solutions":["Make all dict keys the same comparable type (e.g. all strings) before the encoding boundary.","Replace dict keys with a canonical string representation (str(key) or json.dumps) if types must vary.","Convert the dict into a sorted list of key-value pairs of uniform type upstream of the coder.","Inspect the step label in the message to locate the producing transform and fix its output types."],"exampleFix":"// before\ndef to_dict(row):\n    return {row['id']: row['value']}  # id may be int or str\n// after\ndef to_dict(row):\n    return {str(row['id']): row['value']}  # uniform, sortable keys","handlingStrategy":"type-guard","validationCode":"def dict_keys_sortable(d):\n    try:\n        sorted(d.keys()); return True\n    except TypeError:\n        return False","typeGuard":"def has_uniform_keys(d):\n    return bool(d) and len({type(k) for k in d}) == 1 and None not in d","tryCatchPattern":"try:\n    result = p.run()\nexcept TypeError as e:\n    if 'Unable to deterministically order keys of dict' in str(e):\n        normalize_keys_upstream()  # cast all keys to str","preventionTips":["Enforce uniform, non-None key types in transforms producing dicts.","Sort/normalize dict keys (str()) at the boundary of any determinism-required stage.","Add unit tests encoding sample elements with DirectRunner determinism checks."],"tags":["python","coder","determinism","dict","typeerror"],"backgroundTag":"type-mismatch","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"}