BrokenPipeError 32: Fix Writes to Closed Pipes, Sockets

Your script worked for months. Then someone ran it as python report.py | head -5, or a phone client hung up mid-download, and the logs filled with BrokenPipeError: [Errno 32] Broken pipe. The traceback points at an innocent print or sendall, and nothing about your logic looks wrong — because your logic isn't wrong. The reader left.

That mismatch is what makes errno 32 so noisy in production. The exception fires at the exact line that did everything right, so teams treat it like a bug, alert on it like an outage, and burn error-tracker quota on what is really routine traffic: pagers quitting early, clients disconnecting, rotators replacing files. Meanwhile the genuine question — was this output disposable or authoritative — never gets asked.

This article draws that line clearly. You'll learn what errno 32 means at the kernel level, why head and less trigger it, how Python's SIGPIPE handling turns sudden death into a catchable exception, how to handle client disconnects without pager fatigue, exactly when ignoring the error is safe, and the narrow guard pattern that keeps production writes quiet and correct.

What Errno 32 Means: Writing After the Reader Went Away

Errno 32 has the kernel's blunt name: EPIPE, broken pipe. It fires when your process writes to a pipe, FIFO, or socket whose read end has no readers left. The classic sequence is short: the reader — head after five lines, a user quitting less, a phone client hanging up — closes its descriptor, your next write finds nobody home, and the kernel answers with SIGPIPE plus an EPIPE return on the syscall.

What you see in Python is the civilized version of that event. A C program dies on SIGPIPE by default; the Python runtime installs SIG_IGN for SIGPIPE at startup, so the deadly signal is discarded and the failed syscall surfaces as BrokenPipeError, a subclass of OSError with errno set to 32. You get a catchable exception naming the exact write that failed instead of a corpse and exit code 141.

Don't confuse it with its cousins. ECONNRESET (104) means the peer slammed the TCP connection shut with a RST packet; EPIPE means your own write found the local read end gone. Both say the other side left, but they arrive through different kernel paths and sometimes need different handling. Either way the diagnostic move is identical: read the traceback's frame for which descriptor died, ask whether that output was disposable or authoritative, and handle it at the boundary that owns the reader relationship.

import socket

a, b = socket.socketpair()
b.close()  # reader goes away, like quitting `less` mid-stream
count = 0
try:
    while count < 200:
        a.sendall(b"y" * 65536)
        count += 1
    print("no error after", count, "writes")
except (BrokenPipeError, ConnectionResetError) as exc:
    print(type(exc).__name__, "after", count, "writes:", exc)
finally:
    a.close()

Head and Less Closing Stdout: the Classic CLI Crash

The most reported BrokenPipeError in the wild comes from a two-word command: head. You run python report.py | head -5 to preview output, head prints five lines and exits, the shell closes the read end of your stdout pipe, and your next print explodes. Less does the same when the user presses q. Your script is perfectly correct; its audience simply stopped listening early.

The failure timing confuses people because buffering hides it. With block-buffered stdout, small outputs flush once at exit — possibly after the reader left, possibly into a pipe that still accepts bytes — so tiny reports survive while big ones crash. That size dependence sends teams chasing data bugs that don't exist. Run with python -u once and the crash becomes deterministic, which perversely makes it easier to fix.

The fix is a boundary guard, not output surgery. Wrap the producing loop in try/except BrokenPipeError, and in the handler close stdout and stderr quietly (closing stderr avoids a second traceback while the interpreter tears down streams), then sys.exit(0). Exit zero matters: it tells the pipeline your program succeeded, because it did — the reader got everything it asked for. The snippet below reproduces the exact kernel condition with os.pipe so you can practice the pattern without needing head.

import os

r, w = os.pipe()
os.close(r)  # nobody is reading, as when `head` exits early
try:
    os.write(w, b"hello")
    os.write(w, b"x" * 1000000)
    print("write succeeded")
except BrokenPipeError as exc:
    print("BrokenPipeError:", exc)
finally:
    os.close(w)

SIGPIPE and Python's BrokenPipeError: Why You See an Exception

Every Unix C programmer learns SIGPIPE the hard way: write to a readerless pipe and the kernel kills your process with prejudice. No handler runs, no cleanup executes, and the shell reports exit code 141 (128 plus signal 13). That behavior is sane for 1970s filters but brutal for applications that deserve to decide for themselves.

Python decided differently at startup. Before your first line runs, the runtime sets SIGPIPE to SIG_IGN, so the killer signal is silently discarded and the syscall simply returns EPIPE — which the I/O layer raises as BrokenPipeError. That single design choice converts sudden death into a catchable, loggable, testable event. You can verify it any time: signal.getsignal(signal.SIGPIPE) prints SIG_IGN in a normal interpreter.

Two corollaries bite people. First, if you or a native extension reset SIGPIPE to SIG_DFL, you restore silent death — don't, unless a very specific subprocess contract demands it. Second, child processes are a separate world: the subprocess module resets SIGPIPE to SIG_DFL in the child by default, so pipelines like your script feeding a C helper behave with classic Unix semantics on the far side. Know which side of the fork you're on, handle the exception on yours, and leave the signal disposition alone.

import signal
import socket

print("SIGPIPE handler:", signal.getsignal(signal.SIGPIPE))
a, b = socket.socketpair()
b.close()
try:
    a.sendall(b"ping")
except BrokenPipeError as exc:
    print("caught instead of killed:", exc)
finally:
    a.close()

Client Disconnects: Sockets That Close Mid-Response

On the server side, BrokenPipeError is the sound of a client hanging up mid-sentence. Mobile apps lose signal in tunnels, users mash cancel, curl gets Ctrl-C, load-balancer health checks open and abandon connections by design. Your handler is formatting a response nobody will read, the next sendall finds a closed socket, and errno 32 lands in your logs.

At any real scale this is background radiation, not signal. A service doing ten thousand responses a minute will see dozens of hang-ups an hour from normal human behavior alone. Teams that alert on each one train themselves to ignore the alert channel entirely — which is how the 40,000-event weekend in our incident report happened. The disconnect rate is product analytics; it is not an error budget burn.

Handle it at the per-connection boundary with a narrow except clause: catch BrokenPipeError (and its sibling ConnectionResetError), log at debug with the client address for forensics, close the socket, and return. Never retry pushing bytes at a client that hung up — there is nobody to receive them, and retries convert a one-line event into a hot loop. If you need the business signal (abandoned checkouts, dropped downloads), emit a counter, not a traceback.

import socket

srv, cli = socket.socketpair()
cli.close()  # client vanishes mid-response
count = 0
try:
    while count < 200:
        srv.sendall(b"y" * 65536)
        count += 1
    print("no error after", count, "writes")
except (BrokenPipeError, ConnectionResetError) as exc:
    print("client gone after", count, "writes:", type(exc).__name__)
finally:
    srv.close()

When It Is Safe to Ignore: Logs, Pipes, and Fire-and-Forget Writes

Not every BrokenPipeError deserves handling — some deserve deliberate ignoring, and knowing which is which separates calm on-call rotations from noisy ones. Safe to drop: log lines to a collector that restarted, metrics to a fire-and-forget UDP-style sink, paged report output, progress bars, and anything the reader can trivially re-request. These outputs are hints, not records; losing one to a closed reader costs nothing.

Never ignore: data files, billing records, database commits, queue acknowledgments, audit trails — anything where a half-write could be mistaken for a complete one. If the reader's departure leaves your system's state ambiguous, you don't have a pipe problem, you have a durability problem, and swallowing the exception converts it into silent corruption.

The decision rule fits in one sentence: if the bytes are reproducible or disposable, drop them quietly; if they're authoritative, fail loudly and let the retry or reconciliation path run. Encode that rule as a helper like the safe_send below — it returns False for dead readers so callers branch explicitly, while unexpected errors still raise and get the attention they deserve. Explicit branches get reviewed; swallowed exceptions don't.

import errno
import socket

def safe_send(sock, payload):
    try:
        sock.sendall(payload)
        return True
    except BrokenPipeError:
        return False  # reader left; safe to drop logs and metrics
    except OSError as exc:
        if exc.errno in (errno.EPIPE, errno.ESHUTDOWN):
            return False
        raise

live_a, live_b = socket.socketpair()
print("live send ok:", safe_send(live_a, b"hello"))
dead_a, dead_b = socket.socketpair()
dead_b.close()
print("dead send dropped:", safe_send(dead_a, b"hello") is False)
live_a.close()
live_b.close()
dead_a.close()

Production-Safe Writes: Catch, Guard, and Flush in Order

The production pattern has three parts in a fixed order: flush in chunks so failures surface promptly, catch at the boundary so one decision covers every write, and close descriptors quietly so teardown can't raise a second exception. Get the order right and pipe handling becomes a solved problem instead of a recurring ticket.

Chunked flushing is the performance compromise. Flushing every print costs a syscall per line and tanks large reports; never flushing lets megabytes buffer and delays the failure past the point where exiting cleanly is easy. Flushing every few hundred lines — or flushing before a long computation — surfaces a dead reader quickly without measurable cost. Python's print(flush=True) on chunk boundaries is all it takes.

The boundary handler wraps the whole producing loop, not individual prints: try around the loop, except BrokenPipeError that closes stdout then stderr inside a nested guard, then sys.exit(0). Test it the way production will run it: pipe to head -c 0 for the instant-quit case, pipe to head -5 for the mid-stream case, and close a socket mid-response for the server case. The emit helper below shows the shape in miniature — boolean results, no surprise tracebacks, quiet teardown.

import sys

def emit(stream, line):
    try:
        stream.write(line + "\n")
        stream.flush()
        return True
    except BrokenPipeError:
        return False

class DeadStream:
    def write(self, s):
        raise BrokenPipeError(32, "Broken pipe")

    def flush(self):
        pass

print("real stdout:", emit(sys.stdout, "hello"))
print("dead pipe handled:", emit(DeadStream(), "hello") is False)