{"record":{"id":"2db7043c3e4652a7","repo":"apache/beam","slug":"multi-level-initial-splitting-is-not-supported-expected","errorCode":null,"errorMessage":"Multi-level initial splitting is not supported. Expected start and stop positions to be None. Received %r and %r respectively.","messagePattern":"Multi-level initial splitting is not supported\\. Expected start and stop positions to be None\\. Received %r and %r respectively\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/io/concat_source.py","lineNumber":54,"sourceCode":"  to create the union of several reads.\n  \"\"\"\n  def __init__(self, sources):\n    self._source_bundles = [\n        source if isinstance(source, iobase.SourceBundle) else\n        iobase.SourceBundle(None, source, None, None) for source in sources\n    ]\n\n  @property\n  def sources(self):\n    return [s.source for s in self._source_bundles]\n\n  def estimate_size(self):\n    return sum(s.source.estimate_size() for s in self._source_bundles)\n\n  def split(\n      self, desired_bundle_size=None, start_position=None, stop_position=None):\n    if start_position or stop_position:\n      raise ValueError(\n          'Multi-level initial splitting is not supported. Expected start and '\n          'stop positions to be None. Received %r and %r respectively.' %\n          (start_position, stop_position))\n\n    for source in self._source_bundles:\n      # We assume all sub-sources to produce bundles that specify weight using\n      # the same unit. For example, all sub-sources may specify the size in\n      # bytes as their weight.\n      for bundle in source.source.split(desired_bundle_size,\n                                        source.start_position,\n                                        source.stop_position):\n        yield bundle\n\n  def get_range_tracker(self, start_position=None, stop_position=None):\n    if start_position is None:\n      start_position = (0, None)\n    if stop_position is None:\n      stop_position = (len(self._source_bundles), None)","sourceCodeStart":36,"sourceCodeEnd":72,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/io/concat_source.py#L36-L72","documentation":"ConcatSource.split() delegates initial splitting to its sub-sources and does not support multi-level splitting. If the framework passes non-None start_position or stop_position (meaning an outer split already constrained the range), it raises ValueError because splitting a range-restricted concatenation cannot be expressed here.","triggerScenarios":"Calling concat_source.split(desired_bundle_size, start_position, stop_position) with either position set; custom runner or custom source code that splits an already-split ConcatSource bundle.","commonSituations":"Custom composite sources layered over ConcatSource; runners or test harnesses performing repeated/bounded splitting; Beam version changes altering split contracts.","solutions":["Call split() with only desired_bundle_size, leaving start_position/stop_position as None","Flatten nested ConcatSources so only one level of splitting occurs","Implement positions-aware splitting in a custom Source subclass if needed"],"exampleFix":"// before\nbundles = concat_source.split(64 * 1024 * 1024, start_pos, stop_pos)\n// after\nbundles = concat_source.split(desired_bundle_size=64 * 1024 * 1024)  # positions must be None","handlingStrategy":"validation","validationCode":"assert start_position is None and stop_position is None, 'ConcatSource.split supports only unbounded initial splitting'","typeGuard":null,"tryCatchPattern":"try:\n    bundles = source.split(size, start, stop)\nexcept ValueError:\n    bundles = source.split(size)  # retry without position bounds","preventionTips":["Only call split() at the top level with positions=None","Avoid nesting ConcatSource inside position-aware wrappers","Handle this ValueError in custom runner split logic with an unbounded-split fallback"],"tags":["beam","splitting","unsupported-operation"],"backgroundTag":"unsupported-operation","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"}