{"record":{"id":"e439bfe1cd7f6a6b","repo":"python/cpython","slug":"eagain","errorCode":"EAGAIN","errorMessage":"write could not complete without blocking","messagePattern":"write could not complete without blocking","errorType":"exception","errorClass":"BlockingIOError","httpStatus":null,"severity":"warning","filePath":"Lib/_pyio.py","lineNumber":1317,"sourceCode":"            if pos is None:\n                pos = self.raw.tell()\n            return self.raw.truncate(pos)\n\n    def flush(self):\n        with self._write_lock:\n            self._flush_unlocked()\n\n    def _flush_unlocked(self):\n        if self.closed:\n            raise ValueError(\"flush on closed file\")\n        while self._write_buf:\n            try:\n                n = self.raw.write(self._write_buf)\n            except BlockingIOError:\n                raise RuntimeError(\"self.raw should implement RawIOBase: it \"\n                                   \"should not raise BlockingIOError\")\n            if n is None:\n                raise BlockingIOError(\n                    errno.EAGAIN,\n                    \"write could not complete without blocking\", 0)\n            if n > len(self._write_buf) or n < 0:\n                raise OSError(\"write() returned incorrect number of bytes\")\n            del self._write_buf[:n]\n\n    def tell(self):\n        return _BufferedIOMixin.tell(self) + len(self._write_buf)\n\n    def seek(self, pos, whence=0):\n        if whence not in valid_seek_flags:\n            raise ValueError(\"invalid whence value\")\n        with self._write_lock:\n            self._flush_unlocked()\n            return _BufferedIOMixin.seek(self, pos, whence)\n\n    def close(self):\n        with self._write_lock:","sourceCodeStart":1299,"sourceCodeEnd":1335,"githubUrl":"https://github.com/python/cpython/blob/bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6/Lib/_pyio.py#L1299-L1335","documentation":"Raised by BufferedWriter._flush_unlocked when raw.write() returns None — the RawIOBase signal for 'would block' — meaning no bytes could be written right now. The buffer converts that into BlockingIOError(errno.EAGAIN, 'write could not complete without blocking', 0), i.e. a zero-byte partial write, so the caller knows to retry later.","triggerScenarios":"Flushing a BufferedWriter over a non-blocking socket/pipe whose send buffer is full (raw.write returns None); flushing after the peer stopped reading; BufferedWriter.seek()/truncate() on a full non-blocking stream (they flush internally).","commonSituations":"Non-blocking network writers under backpressure; pipe-based producers outrunning consumers; mixing blocking assumptions (assuming flush always completes) with non-blocking fds.","solutions":["Catch BlockingIOError from flush/write and retry once the fd reports writable (selectors.select for EVENT_WRITE).","Put the fd back in blocking mode if you cannot implement backpressure.","Bound the buffered amount yourself (stop writing when pending bytes exceed a watermark) so flush rarely hits EAGAIN."],"exampleFix":"# before\nwriter.flush()  # BlockingIOError on full non-blocking socket\n\n# after\nimport selectors\nsel = selectors.DefaultSelector()\nsel.register(sock, selectors.EVENT_WRITE)\nwhile True:\n    try:\n        writer.flush()\n        break\n    except BlockingIOError:\n        sel.select()  # wait until writable, then retry flush","handlingStrategy":"retry","validationCode":"import selectors\nsel = selectors.DefaultSelector()\nsel.register(sock, selectors.EVENT_WRITE)\nif not sel.select(0):\n    ...  # not writable yet; defer flush\nelse:\n    writer.flush()","typeGuard":null,"tryCatchPattern":"while True:\n    try:\n        writer.flush()\n        break\n    except BlockingIOError:\n        sel.select()  # wait for EVENT_WRITE, retry","preventionTips":["Only flush when the selector reports the fd writable.","Handle characters_written == 0 by backing off and retrying.","Use blocking fds when no backpressure handling exists."],"tags":["python","io","buffered-writer","blockingioerror","eagain","nonblocking","backpressure"],"backgroundTag":null,"analyzedSha":"bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6","analyzedAt":"2026-08-14T22:01:13.976Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}