python/cpython · error · TypeError

an integer is required

Error message

an integer is required

What it means

Raised by FileIO.seek when the pos argument is a float ('an integer is required'). File positions must be integers; a float offset is rejected with TypeError before the closed check and the os.lseek call, mirroring the integer-fd rule in the constructor.

Source

Thrown at Lib/_pyio.py:1796

        try:
            return os.write(self._fd, b)
        except BlockingIOError:
            return None

    def seek(self, pos, whence=SEEK_SET):
        """Move to new file position.

        Argument offset is a byte count.  Optional argument whence defaults
        to SEEK_SET or 0 (offset from start of file, offset should be >= 0);
        other values are SEEK_CUR or 1 (move relative to current position,
        positive or negative), and SEEK_END or 2 (move relative to end of
        file, usually negative, although many platforms allow seeking beyond
        the end of a file).

        Note that not all file objects are seekable.
        """
        if isinstance(pos, float):
            raise TypeError('an integer is required')
        self._checkClosed()
        return os.lseek(self._fd, pos, whence)

    def tell(self):
        """tell() -> int.  Current file position.

        Can raise OSError for non seekable files."""
        self._checkClosed()
        return os.lseek(self._fd, 0, SEEK_CUR)

    def truncate(self, size=None):
        """Truncate the file to at most size bytes.

        Size defaults to the current file position, as returned by tell().
        The current file position is changed to the value of size.
        """
        self._checkClosed()
        self._checkWritable()

View on GitHub (pinned to bc6749cc3b)

Solutions

  1. Convert with int() after ensuring the value is integral: f.seek(int(pos))
  2. Use floor division // where the offset math may produce floats
  3. Round deliberately if truncation is intended and document it: f.seek(int(round(pos)))

Example fix

# before
half = total_len / 2
f.seek(half)          # TypeError: an integer is required (FileIO.seek)

# after
half = total_len // 2
f.seek(half)
Defensive patterns

Strategy: validation

Validate before calling

import math
if not isinstance(pos, int):
    if isinstance(pos, float) and pos.is_integer():
        pos = int(pos)
    else:
        raise TypeError('seek offset must be an integer')
f.seek(pos, whence)

Type guard

def is_int_offset(p):
    return isinstance(p, int) and not isinstance(p, bool)

Try / catch

try:
    f.seek(pos)
except TypeError as e:
    if 'integer' in str(e) and isinstance(pos, float) and pos.is_integer():
        f.seek(int(pos))
    else:
        raise

Prevention

When it happens

Trigger: f.seek(1.5), f.seek(n / 2), or f.seek(numpy.float64(x)) on a FileIO (e.g. buffering=0); offsets computed with true division or read from JSON floats.

Common situations: Offsets produced by division, statistics, or pandas/numpy arithmetic fed into seek; JSON config where the byte offset arrived as 1024.0; porting code where another API accepted float offsets.

Related errors

AI-assisted analysis of python/cpython@bc6749cc3b (2026-08-14). Data as JSON: /api/errors/89265803390e46ce. Report an issue: GitHub.