{"record":{"id":"03e685ad99ec6054","repo":"apache/beam","slug":"start-offset-must-be-a-number-received-r","errorCode":null,"errorMessage":"start_offset must be a number. Received: %r","messagePattern":"start_offset must be a number\\. Received: %r","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/io/filebasedsource.py","lineNumber":252,"sourceCode":"def _determine_splittability_from_compression_type(file_path, compression_type):\n  if compression_type == CompressionTypes.AUTO:\n    compression_type = CompressionTypes.detect_compression_type(file_path)\n\n  return compression_type == CompressionTypes.UNCOMPRESSED\n\n\nclass _SingleFileSource(iobase.BoundedSource):\n  \"\"\"Denotes a source for a specific file type.\"\"\"\n  def __init__(\n      self,\n      file_based_source,\n      file_name,\n      start_offset,\n      stop_offset,\n      min_bundle_size=0,\n      splittable=True):\n    if not isinstance(start_offset, int):\n      raise TypeError(\n          'start_offset must be a number. Received: %r' % start_offset)\n    if stop_offset != range_trackers.OffsetRangeTracker.OFFSET_INFINITY:\n      if not isinstance(stop_offset, int):\n        raise TypeError(\n            'stop_offset must be a number. Received: %r' % stop_offset)\n      if start_offset >= stop_offset:\n        raise ValueError(\n            'start_offset must be smaller than stop_offset. Received %d and %d '\n            'for start and stop offsets respectively' %\n            (start_offset, stop_offset))\n\n    self._file_name = file_name\n    self._is_gcs_file = file_name.startswith('gs://') if file_name else False\n    self._start_offset = start_offset\n    self._stop_offset = stop_offset\n    self._min_bundle_size = min_bundle_size\n    self._file_based_source = file_based_source\n    self._splittable = splittable","sourceCodeStart":234,"sourceCodeEnd":270,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/io/filebasedsource.py#L234-L270","documentation":"_FileBasedSource.__init__ requires start_offset to be an int and raises TypeError when it is not. Offsets are byte/record positions used for dynamic work rebalancing, so a non-numeric start offset is rejected immediately. Note that bools are ints in Python but floats/strings/None are not accepted.","triggerScenarios":"Constructing a _FileBasedSource (or subclass like _TextSource/_AvroSource) with start_offset as a float, string, or None; passing a value read from config/CLI as a string; arithmetic producing a float (e.g. file_size / 2).","commonSituations":"Deserializing offsets from JSON where they become strings or floats; dividing file sizes with '/' instead of '//'; passing None after a failed lookup.","solutions":["Pass an integer: convert with int(start_offset) or use floor division //","Validate the offset type before constructing the source","Fix the upstream config/parser so offsets are parsed as ints"],"exampleFix":"// before\nsrc = _FileBasedSource(path, file_size / 2, file_size)\n// after\nsrc = _FileBasedSource(path, int(file_size // 2), file_size)","handlingStrategy":"validation","validationCode":"if not isinstance(start_offset, int) or isinstance(start_offset, bool):\n    raise TypeError(f'start_offset must be int, got {type(start_offset).__name__}')","typeGuard":"def is_valid_offset(v) -> bool:\n    return isinstance(v, int) and not isinstance(v, bool) and v >= 0","tryCatchPattern":"try:\n    src = _FileBasedSource(path, start, stop)\nexcept TypeError as e:\n    if 'start_offset must be a number' in str(e):\n        start = int(start)\n        src = _FileBasedSource(path, start, stop)\n    else:\n        raise","preventionTips":["Use // for integer division when computing byte offsets","Coerce config/JSON offsets with int() at parse time","Never pass None as an offset; use OFFSET_INFINITY for end-of-file"],"tags":["type-mismatch","offset","constructor"],"backgroundTag":"type-mismatch","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"}