What causes "Whence mode %r is invalid." in apache/beam?

Pass only os.SEEK_SET, os.SEEK_CUR, or os.SEEK_END as whence.

apache/beam · error · ValueError

Whence mode %r is invalid.

Error message

Whence mode %r is invalid.

What it means

FilesystemIO (downloader/reader-backed streams) seek() accepts only os.SEEK_SET, os.SEEK_CUR, and os.SEEK_END; any other whence value hits the else branch and raises ValueError('Whence mode %r is invalid.'). The position is then clamped to [0, size], but the whence itself must be one of the three constants.

Solutions

Pass only os.SEEK_SET, os.SEEK_CUR, or os.SEEK_END as whence.
Use the default (SEEK_SET) by calling seek(offset) without a whence argument.
Validate whence before calling: `assert whence in (os.SEEK_SET, os.SEEK_CUR, os.SEEK_END)`.
Replace arbitrary jumps with explicit re-open of the stream when random access isn't needed.

Example fix

// before
f.seek(-1, 3)  # ValueError: Whence mode 3 is invalid.
// after
import os
f.seek(-1, os.SEEK_END)

Defensive patterns

Strategy: validation

Validate before calling

import os
assert whence in (os.SEEK_SET, os.SEEK_CUR, os.SEEK_END), f'bad whence: {whence!r}'

Type guard

def is_valid_whence(whence) -> bool:
    import os
    return isinstance(whence, int) and whence in (os.SEEK_SET, os.SEEK_CUR, os.SEEK_END)

Try / catch

try:
    pos = f.seek(offset, whence)
except ValueError as e:
    if 'Whence mode' in str(e):
        pos = f.seek(offset)  # default SEEK_SET
    else:
        raise

Prevention

Use only os.SEEK_SET/CUR/END constants for whence on all file-like wrappers.
Normalize string whence ('set','cur','end') to os constants at your wrapper's boundary.
Test seek() with all three whence values in stream unit tests.

When it happens

Trigger: Calling seek(offset, whence) on a stream obtained from FileSystems.open()/FileSystems.download() with whence not in {0,1,2} — e.g. seek(0, 'begin'), seek(-10, 5), or a non-integer sentinel.

Common situations: Hand-rolling file-like wrappers that pass through a custom whence enum; copy-pasted code from libraries that allow string whence values like 'end'.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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

Appendix: source

Thrown at sdks/python/apache_beam/io/filesystemio.py:140

    Args:
      offset: seek offset as number.
      whence: seek mode. Supported modes are os.SEEK_SET (absolute seek),
        os.SEEK_CUR (seek relative to the current position), and os.SEEK_END
        (seek relative to the end, offset should be negative).

    Raises:
      ``ValueError``: When this stream is closed or if whence is invalid.
    """
    self._checkClosed()

    if whence == os.SEEK_SET:
      self._position = offset
    elif whence == os.SEEK_CUR:
      self._position += offset
    elif whence == os.SEEK_END:
      self._position = self._downloader.size + offset
    else:
      raise ValueError('Whence mode %r is invalid.' % whence)

    self._position = min(self._position, self._downloader.size)
    self._position = max(self._position, 0)
    return self._position

  def tell(self):
    """Tell the stream's current offset.

    Returns:
      current offset in reading this stream.

    Raises:
      ``ValueError``: When this stream is closed.
    """
    self._checkClosed()
    return self._position

  def seekable(self):

View on GitHub (pinned to 12126d8942)