{"record":{"id":"77bc29db3593b402","repo":"apache/beam","slug":"ignore-first-n-seen-per-batch-size-s-must-be-non-negative","errorCode":null,"errorMessage":"ignore_first_n_seen_per_batch_size (%s) must be non negative","messagePattern":"ignore_first_n_seen_per_batch_size \\((.+?)\\) must be non negative","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/transforms/util.py","lineNumber":545,"sourceCode":"          (target_batch_overhead))\n    if target_batch_duration_secs and target_batch_duration_secs <= 0:\n      raise ValueError(\n          \"target_batch_duration_secs (%s) must be positive\" %\n          (target_batch_duration_secs))\n    if (target_batch_duration_secs_including_fixed_cost and\n        target_batch_duration_secs_including_fixed_cost <= 0):\n      raise ValueError(\n          \"target_batch_duration_secs_including_fixed_cost \"\n          \"(%s) must be positive\" %\n          (target_batch_duration_secs_including_fixed_cost))\n    if not (target_batch_overhead or target_batch_duration_secs or\n            target_batch_duration_secs_including_fixed_cost):\n      raise ValueError(\n          \"At least one of target_batch_overhead or \"\n          \"target_batch_duration_secs or \"\n          \"target_batch_duration_secs_including_fixed_cost must be positive.\")\n    if ignore_first_n_seen_per_batch_size < 0:\n      raise ValueError(\n          'ignore_first_n_seen_per_batch_size (%s) must be non '\n          'negative' % (ignore_first_n_seen_per_batch_size))\n    self._min_batch_size = min_batch_size\n    self._max_batch_size = max_batch_size\n    self._target_batch_overhead = target_batch_overhead\n    self._target_batch_duration_secs = target_batch_duration_secs\n    self._target_batch_duration_secs_including_fixed_cost = (\n        target_batch_duration_secs_including_fixed_cost)\n    self._variance = variance\n    self._clock = clock\n    self._data = []\n    self._ignore_next_timing = False\n    self._ignore_first_n_seen_per_batch_size = (\n        ignore_first_n_seen_per_batch_size)\n    self._batch_size_num_seen = {}\n    self._replay_last_batch_size = None\n    self._record_metrics = record_metrics\n    self._element_count = 0","sourceCodeStart":527,"sourceCodeEnd":563,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/transforms/util.py#L527-L563","documentation":"Raised in _BatchSizeEstimator (BatchElements) __init__ when ignore_first_n_seen_per_batch_size is negative. This parameter controls how many initial observations per batch size are ignored for warm-up; a negative count is meaningless and rejected with ValueError.","triggerScenarios":"BatchElements(ignore_first_n_seen_per_batch_size=-1) or computing the value from a formula that can go negative.","commonSituations":"Config arithmetic like desired - observed where observed > desired; a default of -1 used as a sentinel clashing with validation.","solutions":["Pass a non-negative integer (0 to disable warm-up skipping).","Clamp the computed value: ignore_n = max(0, computed).","Validate config values before constructing the transform."],"exampleFix":"// before\nbeam.BatchElements(target_batch_overhead=0.05, ignore_first_n_seen_per_batch_size=-3)\n\n// after\nbeam.BatchElements(target_batch_overhead=0.05, ignore_first_n_seen_per_batch_size=max(0, ignore_n))","handlingStrategy":"validation","validationCode":"if ignore_first_n_seen_per_batch_size < 0:\n    raise ValueError('ignore_first_n_seen_per_batch_size must be >= 0')","typeGuard":"def valid_warmup_skip(n):\n    return isinstance(n, int) and n >= 0","tryCatchPattern":"try:\n    t = beam.BatchElements(target_batch_overhead=0.05, ignore_first_n_seen_per_batch_size=n)\nexcept ValueError:\n    t = beam.BatchElements(target_batch_overhead=0.05, ignore_first_n_seen_per_batch_size=max(0, n))","preventionTips":["Clamp computed warm-up values with max(0, value).","Avoid -1 as a 'disabled' sentinel; use 0 or None semantics explicitly.","Validate the value wherever it is read from config or CLI flags."],"tags":["python","apache-beam","batchelements","config-validation"],"backgroundTag":"value-out-of-range","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"}