apache/beam · error · ValueError

File object must be at position 0 but was

Error message

File object must be at position 0 but was %d

What it means

CompressedFile assumes it starts reading/writing a fresh compressed stream, so the wrapped file object must be positioned at byte 0. If file.tell() reports any other offset, the compressed stream would be corrupted/misread, so __init__ raises ValueError with the offending position.

Solutions

1. Call fh.seek(0) before constructing CompressedFile.
2. Open a fresh file handle for the CompressedFile instead of reusing one.
3. If resuming mid-stream is required, use a random-access reader (e.g. FileSystems.open with seek support) rather than CompressedFile.

Example fix

// before
fh.read(10)
reader = CompressedFile(fh, compression_type=CompressionTypes.GZIP)
// after
fh.seek(0)
reader = CompressedFile(fh, compression_type=CompressionTypes.GZIP)

if fh.tell() != 0:
    fh.seek(0)
reader = CompressedFile(fh, compression_type=CompressionTypes.GZIP)

When it happens

Trigger: Opening a file, calling fh.seek(n) or fh.read(...) and then wrapping it in CompressedFile; reusing a partially consumed file handle.

Common situations: Reusing a file object after an earlier read pass, retry logic that rewinds improperly, or pipes/stream objects whose position advanced before construction.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• A schema is required to write non-schema'd data.
• A sink must inherit iobase.Sink, iobase.NativeSink, or be a…
• An explicit schema is required to write non-schema'd…
• Cannot call read after iterating.
• Cannot create a temporary directory for root path prefix

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

Appendix: source

Thrown at sdks/python/apache_beam/io/filesystem.py:165

      compression_type=CompressionTypes.GZIP,
      read_size=DEFAULT_READ_BUFFER_SIZE):
    if not fileobj:
      raise ValueError('File object must not be None')

    if not CompressionTypes.is_valid_compression_type(compression_type):
      raise TypeError(
          'compression_type must be CompressionType object but '
          'was %s' % type(compression_type))
    if compression_type in (CompressionTypes.AUTO,
                            CompressionTypes.UNCOMPRESSED):
      raise ValueError(
          'Cannot create object with unspecified or no compression')

    self._file = fileobj
    self._compression_type = compression_type

    if self._file.tell() != 0:
      raise ValueError(
          'File object must be at position 0 but was %d' % self._file.tell())
    self._uncompressed_position = 0
    self._uncompressed_size: Optional[int] = None

    if self.readable():
      self._read_size = read_size
      self._read_buffer = io.BytesIO()
      self._read_position = 0
      self._read_eof = False

      self._initialize_decompressor()
    else:
      self._decompressor = None

    if self.writeable():
      self._initialize_compressor()
    else:
      self._compressor = None

View on GitHub (pinned to 12126d8942)