apache/beam · error · ValueError

Expected weight to be > 0 for %s but received %d

Error message

Expected weight to be > 0 for %s but received %d

What it means

StateCacheWeightedValue wraps a cache value together with a weight (its effective cost in the cache). Because weights drive cache eviction arithmetic, a weight of zero or negative would corrupt the cache's size accounting, so the constructor raises ValueError for any weight <= 0.

Source

Thrown at sdks/python/apache_beam/runners/worker/statecache.py:62

    # Do not measure lambdas as they typically share lots of state
    types.FunctionType,
    types.LambdaType,
    # Do not measure weak references as they will be deleted and not counted
    *weakref.ProxyTypes,
    weakref.ReferenceType)


class WeightedValue(object):
  """Value type that stores corresponding weight.

  :arg value The value to be stored.
  :arg weight The associated weight of the value. If unspecified, the objects
  size will be used.
  """
  def __init__(self, value: Any, weight: int) -> None:
    self._value = value
    if weight <= 0:
      raise ValueError(
          'Expected weight to be > 0 for %s but received %d' % (value, weight))
    self._weight = weight

  def weight(self) -> int:
    return self._weight

  def value(self) -> Any:
    return self._value


class CacheAware(object):
  """Allows cache users to override what objects are measured."""
  def __init__(self) -> None:
    pass

  def get_referents_for_cache(self) -> list[Any]:
    """Returns the list of objects accounted during cache measurement."""
    raise NotImplementedError()

View on GitHub (pinned to 12126d8942)

Solutions

  1. Ensure the weight passed is a positive integer; clamp with max(1, computed_weight)
  2. Fix the size-estimation function so empty values still report a minimum positive weight
  3. Remove placeholder weight=0 calls and use the object's real size

Example fix

// before
entry = StateCacheWeightedValue(value, len(serialized) - 1)  # may be <= 0
// after
weight = max(1, len(serialized))
entry = StateCacheWeightedValue(value, weight)
Defensive patterns

Strategy: validation

Validate before calling

def make_cache_value(value, weight_fn):
    w = weight_fn(value)
    if not isinstance(w, int) or w <= 0:
        w = 1  # clamp before constructing
    return StateCacheWeightedValue(value, w)

Type guard

def valid_weight(w) -> bool:
    return isinstance(w, int) and w > 0

Try / catch

try:
    entry = StateCacheWeightedValue(value, computed_weight)
except ValueError as e:
    if 'Expected weight to be > 0' in str(e):
        entry = StateCacheWeightedValue(value, 1)
    else:
        raise

Prevention

When it happens

Trigger: Calling StateCacheWeightedValue(value, weight) with weight <= 0, e.g. passing 0, a negative size, or a size-computation function that returned 0 or a negative number for an empty/zero-sized object.

Common situations: Custom weight functions (object size estimators) returning 0 for empty payloads or returning -1 on error; hardcoding weight=0 to 'disable' caching; integer overflow in size computations producing negative values.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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