{"record":{"id":"0eebd517e09a7873","repo":"python/cpython","slug":"invalid-buffering-size","errorCode":null,"errorMessage":"invalid buffering size","messagePattern":"invalid buffering size","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"Lib/_pyio.py","lineNumber":249,"sourceCode":"                      \"mode, the default buffer size will be used\",\n                      RuntimeWarning, 2)\n    raw = FileIO(file,\n                 (creating and \"x\" or \"\") +\n                 (reading and \"r\" or \"\") +\n                 (writing and \"w\" or \"\") +\n                 (appending and \"a\" or \"\") +\n                 (updating and \"+\" or \"\"),\n                 closefd, opener=opener)\n    result = raw\n    try:\n        line_buffering = False\n        if buffering == 1 or buffering < 0 and raw._isatty_open_only():\n            buffering = -1\n            line_buffering = True\n        if buffering < 0:\n            buffering = max(min(raw._blksize, 8192 * 1024), DEFAULT_BUFFER_SIZE)\n        if buffering < 0:\n            raise ValueError(\"invalid buffering size\")\n        if buffering == 0:\n            if binary:\n                return result\n            raise ValueError(\"can't have unbuffered text I/O\")\n        if updating:\n            buffer = BufferedRandom(raw, buffering)\n        elif creating or writing or appending:\n            buffer = BufferedWriter(raw, buffering)\n        elif reading:\n            buffer = BufferedReader(raw, buffering)\n        else:\n            raise ValueError(\"unknown mode: %r\" % mode)\n        result = buffer\n        if binary:\n            return result\n        encoding = text_encoding(encoding)\n        text = TextIOWrapper(buffer, encoding, errors, newline, line_buffering)\n        result = text","sourceCodeStart":231,"sourceCodeEnd":267,"githubUrl":"https://github.com/python/cpython/blob/bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6/Lib/_pyio.py#L231-L267","documentation":"Raised by io.open() as a ValueError when the buffering size is still negative after the default-size resolution step. The code maps buffering<0 (and buffering==1 on a tty) to a computed default from the raw device block size; this raise is a defensive assertion that the computed size is non-negative. With the standard formula max(min(blksize, 8MB), DEFAULT_BUFFER_SIZE) it is effectively unreachable through the public API.","triggerScenarios":"Not reachable via normal open() calls: any negative buffering is replaced by a default >= DEFAULT_BUFFER_SIZE (8192). It could only fire if the underlying raw FileIO reported a corrupt/absurd _blksize such that the computed default stayed negative, or in patched/alternative IO stacks that reuse this logic with different constants.","commonSituations":"Developers grep this message after seeing it from a monkeypatched or reimplemented open (test doubles, custom raw IO classes in embedded interpreters, vendored _pyio with modified constants). Standard CPython users do not hit it.","solutions":["If you control the raw IO class, ensure its _blksize attribute is a sane positive int.","Pass an explicit positive buffering value (e.g. 64*1024) to bypass default-size computation.","If you patched _pyio/open constants, restore them or recompute the default so it is non-negative."],"exampleFix":"// before\nclass OddRaw(io.RawIOBase):\n    _blksize = -1        # corrupt block size defeats default resolution\nopen('f', 'rb', buffering=-1, ...)   # defensive ValueError path\n\n// after\nclass OddRaw(io.RawIOBase):\n    _blksize = io.DEFAULT_BUFFER_SIZE\n# or sidestep defaults:\nopen('f', 'rb', buffering=65536)","handlingStrategy":"validation","validationCode":"if buffering is not None and buffering <= 0:\n    buffering = io.DEFAULT_BUFFER_SIZE   # never hand negative sizes around\nopen(path, buffering=buffering if buffering is not None else -1)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pass explicit positive buffering values in environments with custom raw IO classes.","If you implement RawIOBase subclasses, set _blksize to a sane positive int.","Treat this message as a signal that the IO stack is patched, not that your open() call is wrong."],"tags":["io","open","buffering","valueerror","defensive"],"backgroundTag":null,"analyzedSha":"bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6","analyzedAt":"2026-08-14T22:01:13.976Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}