python/cpython · error · OSError

"raw" argument must be readable.

Error message

"raw" argument must be readable.

What it means

Raised by the BufferedReader constructor when the supplied raw stream is not readable (raw.readable() returns False). BufferedReader is strictly a read-side wrapper, so it validates the raw object's capability at construction time and raises OSError (not ValueError) with the quoted-argument message.

Source

Thrown at Lib/_pyio.py:1060

        return True


class BufferedReader(_BufferedIOMixin):

    """BufferedReader(raw[, buffer_size])

    A buffer for a readable, sequential BaseRawIO object.

    The constructor creates a BufferedReader for the given readable raw
    stream and buffer_size. If buffer_size is omitted, DEFAULT_BUFFER_SIZE
    is used.
    """

    def __init__(self, raw, buffer_size=DEFAULT_BUFFER_SIZE):
        """Create a new buffered reader using the given readable raw IO object.
        """
        if not raw.readable():
            raise OSError('"raw" argument must be readable.')

        _BufferedIOMixin.__init__(self, raw)
        if buffer_size <= 0:
            raise ValueError("invalid buffer size")
        self.buffer_size = buffer_size
        self._reset_read_buf()
        self._read_lock = Lock()

    def readable(self):
        return self.raw.readable()

    def _reset_read_buf(self):
        self._read_buf = b""
        self._read_pos = 0

    def read(self, size=None):
        """Read size bytes.

View on GitHub (pinned to bc6749cc3b)

Solutions

1. Pass a readable raw stream: open the file in 'rb', use the pipe read end, or the correct socket half.
2. For custom raw classes, override readable() to return True when reads are supported.
3. Check raw.readable() yourself before wrapping to give a clearer upstream error.

Example fix

# before
r, w = os.pipe()
reader = io.BufferedReader(os.fdopen(w, 'wb'))  # write end -> OSError

# after
r, w = os.pipe()
reader = io.BufferedReader(os.fdopen(r, 'rb'))

if not raw.readable():
    raise ValueError("supplied raw stream does not support reading")
reader = io.BufferedReader(raw)

def is_readable_raw(obj) -> bool:
    return hasattr(obj, "readable") and callable(getattr(obj, "read")) and obj.readable()

try:
    reader = io.BufferedReader(raw)
except OSError as e:
    raise ValueError(f"need the read end, got: {raw!r}") from e

When it happens

Trigger: io.BufferedReader(raw) where raw is write-only, e.g. another BufferedWriter, an os.pipe write end wrapped with os.fdopen(wfd, 'wb'), or a custom RawIO whose readable() returns False.

Common situations: Mixing up the read and write ends of a pipe; wrapping a socket/file opened for writing only; passing the wrong half of a socketpair; custom raw streams that forgot to override readable() (RawIOBase default returns False).

Related errors

• "raw" argument must be writable.
• "reader" argument must be readable.
• "writer" argument must be writable.
• invalid buffer size
• invalid number of bytes to read

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