apache/beam · error · ValueError

ApproximateUnique needs an estimation error between 0.01…

Error message

ApproximateUnique needs an estimation error between 0.01 and 0.50. Received {error = %s}.

What it means

When error is given, parse_input_params requires 0.01 <= error <= 0.50; outside that range _INPUT_ERROR_ERR_MSG is raised. This mirrors the size constraint: error is about 2/sqrt(sample_size), so errors below 1% need impractically large samples and errors above 50% are meaningless.

Solutions

1. Choose an error between 0.01 and 0.50, e.g. 0.02 for ~2% error.
2. If a percentage was intended, divide by 100 (5 -> 0.05).
3. For tighter precision than 1%, use exact deduplication (beam.Distinct) instead of ApproximateUnique.
4. Ensure the value is a float, not a string, before passing it.

Example fix

// before
beam.ApproximateUnique(error=0.001)
// after
beam.ApproximateUnique(error=0.02)  # within [0.01, 0.50]

if error is not None:
    error = float(error)
    assert 0.01 <= error <= 0.50, f'error must be in [0.01, 0.50], got {error}'

def is_valid_estimation_error(error) -> bool:
    try:
        return 0.01 <= float(error) <= 0.50
    except (TypeError, ValueError):
        return False

try:
    t = beam.ApproximateUnique(error=error)
except ValueError as e:
    if 'estimation error' in str(e):
        clamped = min(0.5, max(0.01, float(error)))
        t = beam.ApproximateUnique(error=clamped)
    else:
        raise

When it happens

Trigger: beam.ApproximateUnique(error=0.005) (too precise) or error=0.9 (too loose); error passed as a string like '0.02' that compares incorrectly or is otherwise out of range.

Common situations: Users expecting high precision (e.g. 0.1% error); config strings converted to numbers incorrectly; mistaking the value for a percentage (5 instead of 0.05).

Related errors

• ApproximateUnique needs a size >= 16 for an error <= 0.50…
• Cannot set position to
• Either size or error should be set. Received
• Either size or error should be set. Received
• PartitionFn specified out-of-bounds partition index

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/6137b39977cf5ff9. Report an issue: GitHub.

Appendix: source

Thrown at sdks/python/apache_beam/transforms/stats.py:132

      _get_sample_size_from_est_error function.
    :return: sample size
    :raises:
      ValueError: If both size and error are given, or neither is given, or
      values are out of range.
    """

    if None not in (size, error):
      raise ValueError(ApproximateUnique._MULTI_VALUE_ERR_MSG % (size, error))
    elif size is None and error is None:
      raise ValueError(ApproximateUnique._NO_VALUE_ERR_MSG)
    elif size is not None:
      if not isinstance(size, int) or size < 16:
        raise ValueError(ApproximateUnique._INPUT_SIZE_ERR_MSG % (size))
      else:
        return size
    else:
      if error < 0.01 or error > 0.5:
        raise ValueError(ApproximateUnique._INPUT_ERROR_ERR_MSG % (error))
      else:
        return ApproximateUnique._get_sample_size_from_est_error(error)

  @staticmethod
  def _get_sample_size_from_est_error(est_err):
    """
    :return: sample size

    Calculate sample size from estimation error
    """
    return math.ceil(4.0 / math.pow(est_err, 2.0))

  @typehints.with_input_types(T)
  @typehints.with_output_types(int)
  class Globally(PTransform):
    """ Approximate.Globally approximate number of unique values"""
    def __init__(self, size=None, error=None):
      self._sample_size = ApproximateUnique.parse_input_params(size, error)

View on GitHub (pinned to 12126d8942)