{"record":{"id":"5e6a9944be8ae31c","repo":"apache/beam","slug":"runtime-exception-s","errorCode":null,"errorMessage":"Runtime exception: %s","messagePattern":"Runtime exception: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/transforms/stats.py","lineNumber":263,"sourceCode":"  \"\"\"\n  def __init__(self, sample_size, coder):\n    self._sample_size = sample_size\n    coder = coders.typecoders.registry.verify_deterministic(\n        coder, 'ApproximateUniqueCombineFn')\n\n    self._coder = coder\n    self._hash_fn = _get_default_hash_fn()\n\n  def create_accumulator(self, *args, **kwargs):\n    return _LargestUnique(self._sample_size)\n\n  def add_input(self, accumulator, element, *args, **kwargs):\n    try:\n      hashed_value = self._hash_fn(self._coder.encode(element))\n      accumulator.add(hashed_value)\n      return accumulator\n    except Exception as e:\n      raise RuntimeError(\"Runtime exception: %s\" % e)\n\n  # created an issue https://github.com/apache/beam/issues/19459 to speed up\n  # merge process.\n  def merge_accumulators(self, accumulators, *args, **kwargs):\n    merged_accumulator = self.create_accumulator()\n    for accumulator in accumulators:\n      for i in accumulator._sample_heap:\n        merged_accumulator.add(i)\n\n    return merged_accumulator\n\n  @staticmethod\n  def extract_output(accumulator):\n    return accumulator.get_estimate()\n\n  def display_data(self):\n    return {'sample_size': self._sample_size}\n","sourceCodeStart":245,"sourceCodeEnd":281,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/transforms/stats.py#L245-L281","documentation":"ApproximateUnique's AddInput transform wraps any exception raised while hashing/encoding an element into a RuntimeError with the original message embedded. This is a coarse wrapper added so worker-side failures surface with context, but it obscures the underlying error (e.g. a coder or hash function failure). The real cause is the wrapped exception text after 'Runtime exception:'.","triggerScenarios":"Calling apache_beam.transforms.stats.ApproximateUnique combine_fn's add_input (directly or via a pipeline) when self._coder.encode(element) raises (element not encodable by the configured coder) or self._hash_fn raises (custom hash function fails on the encoded bytes).","commonSituations":"Pipelines where the element type does not match the coder supplied to ApproximateUnique.Globally()/PerKey(); custom --hash_fn values (e.g. 'cityhash'/'farmhash' selected but the C extension is unavailable in the environment); elements containing types the default varint coder cannot handle.","solutions":["Read the text after 'Runtime exception: ' to find the real error; fix that underlying cause first.","Verify the element type flowing into ApproximateUnique matches its coder argument; pass an explicit coder if needed.","If using a non-default hash, confirm the required hash library is installed in the runner environment or revert to the default hash.","Test the hash of one element locally: hasher(coder.encode(sample)) to reproduce before launching the pipeline."],"exampleFix":"// before\npcoll | ApproximateUnique.Globally(1000)  # elements are dicts, default coder fails\n// after\npcoll | Map(lambda d: json.dumps(d, sort_keys=True)) | ApproximateUnique.Globally(1000)","handlingStrategy":"try-catch","validationCode":"from apache_beam import coders\ntry:\n    encoded = my_coder.encode(sample_element)\nexcept Exception as e:\n    raise ValueError(f'Element not encodable by {my_coder}: {e}')","typeGuard":"def encodable(coder, element):\n    try:\n        coder.encode(element)\n        return True\n    except Exception:\n        return False","tryCatchPattern":"try:\n    result = pcoll | ApproximateUnique.Globally(n)\nexcept RuntimeError as e:\n    logger.error('ApproximateUnique underlying failure: %s', e)\n    # inspect inner message: coder vs hash_fn cause","preventionTips":["Match the coder to the element type explicitly when calling ApproximateUnique.","Pre-map complex elements to strings/bytes before hashing.","Verify optional hash backends (e.g. cityhash/farmhash) are installed in the runner image.","Smoke-test hash_fn(coder.encode(sample)) locally before launching."],"tags":["python","apache-beam","transforms","hashing","runtime-exception"],"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"}