apache/beam · error · ValueError

Per element sleep time must be at least 1e-3. Received: %r

Error message

Per element sleep time must be at least 1e-3. Received: %r

What it means

SyntheticStep.__init__ enforces that a nonzero per_element_delay_sec is at least 1e-3 seconds, because per-element sleeps are implemented with time granularity finer delays cannot honor. Values like 0.0005 are rejected with ValueError.

Solutions

Set per_element_delay_sec >= 0.001, or use 0 to disable per-element delay
Convert your desired delay into per-bundle delay (per_bundle_delay_sec) if sub-millisecond per-element pauses are needed
Update the config spec producing the value

Example fix

// before
SyntheticStep(per_element_delay_sec=0.0001)
// after
SyntheticStep(per_element_delay_sec=0.001)  # or per_bundle_delay_sec=0.0001*batch

Defensive patterns

Strategy: validation

Validate before calling

if per_element_delay_sec and per_element_delay_sec < 1e-3:
    raise ValueError('per_element_delay_sec must be 0 or >= 1e-3')

Type guard

def valid_delay(v):
    return not v or v >= 1e-3

Try / catch

try:
    step = SyntheticStep(per_element_delay_sec=d)
except ValueError as e:
    _LOGGER.error('%s; clamping to 1e-3', e)
    step = SyntheticStep(per_element_delay_sec=1e-3)

Prevention

Clamp delays to >= 0.001 in spec-loading code
Keep all delay values in seconds consistently
Validate the whole synthetic spec before building the pipeline

When it happens

Trigger: Constructing SyntheticStep with per_element_delay_sec between 0 and 1e-3 (exclusive), e.g. 0.0001; 0 itself is allowed since the check is guarded by truthiness.

Common situations: Config JSON generated by tools specifying sub-millisecond delays; unit confusion (microseconds vs seconds); blindly scaling delays down.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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

Appendix: source

Thrown at sdks/python/apache_beam/testing/synthetic_pipeline.py:154

      break
    stop = start + int(num_total_records * relative_bundle_sizes[index])
    bundle_ranges.append((start, stop))
    start = stop
    index += 1
  return bundle_ranges


class SyntheticStep(beam.DoFn):
  """A DoFn of which behavior can be controlled through prespecified parameters.
  """
  def __init__(
      self,
      per_element_delay_sec=0,
      per_bundle_delay_sec=0,
      output_records_per_input_record=1,
      output_filter_ratio=0):
    if per_element_delay_sec and per_element_delay_sec < 1e-3:
      raise ValueError(
          'Per element sleep time must be at least 1e-3. '
          'Received: %r',
          per_element_delay_sec)
    self._per_element_delay_sec = per_element_delay_sec
    self._per_bundle_delay_sec = per_bundle_delay_sec
    self._output_records_per_input_record = output_records_per_input_record
    self._output_filter_ratio = output_filter_ratio

  def start_bundle(self):
    self._start_time = time.time()

  def finish_bundle(self):
    # The target is for the enclosing stage to take as close to as possible
    # the given number of seconds, so we only sleep enough to make up for
    # overheads not incurred elsewhere.
    to_sleep = self._per_bundle_delay_sec - (time.time() - self._start_time)

    # Ignoring sub-millisecond sleep times.

View on GitHub (pinned to 12126d8942)