BlockingIOError [Errno 11] Resource temporarily unavailable (tested)

BlockingIOError: [Errno 11] Resource temporarily unavailable means a non-blocking call had nothing to do yet. We reproduced it from sockets and file locks on Python 3.13.5 and measured the fix.

1. A non-blocking socket with nothing to read

import socket
a, b = socket.socketpair()
a.setblocking(False)
try:
    a.recv(1024)          # nothing has been sent yet
except BlockingIOError as e:
    print(type(e).__name__, e.errno, e)
    print("is OSError:", isinstance(e, OSError))
b.send(b"hello")
print("after send:", a.recv(1024))

Output:

BlockingIOError 11 [Errno 11] Resource temporarily unavailable
is OSError: True
after send: b'hello'

Measured on Python 3.13.5: on a non-blocking socket, recv() with no data waiting raises BlockingIOError with errno 11 (EAGAIN, the same number as EWOULDBLOCK on Linux). It isn't a failure: it means "try again later". Once data arrives the same call works. socket.error is just OSError, so old except socket.error code catches this too.

2. settimeout(0) is non-blocking

import socket
a, b = socket.socketpair()
a.settimeout(0.5)         # a timeout, not non-blocking
try:
    a.recv(1024)
except Exception as e:
    print("settimeout(0.5):", type(e).__name__, e)
a.settimeout(0)           # 0 means non-blocking
try:
    a.recv(1024)
except Exception as e:
    print("settimeout(0):  ", type(e).__name__, e)

Output:

settimeout(0.5): TimeoutError timed out
settimeout(0):   BlockingIOError [Errno 11] Resource temporarily unavailable

Measured: a positive timeout gives TimeoutError after waiting; settimeout(0) is the same as setblocking(False) and gives errno 11 immediately. If you see errno 11 and meant to wait, check for a timeout of 0 (or a computed timeout that hit 0).

3. fcntl.flock with LOCK_NB: someone else holds the lock

import fcntl, subprocess, sys
# Another process holds an exclusive lock on app.lock for 2 seconds
holder = subprocess.Popen([sys.executable, "-c",
    "import fcntl,time; f=open('app.lock','w'); fcntl.flock(f, fcntl.LOCK_EX); print('locked', flush=True); time.sleep(2)"],
    stdout=subprocess.PIPE, text=True)
holder.stdout.readline()
f = open("app.lock", "w")
try:
    fcntl.flock(f, fcntl.LOCK_EX | fcntl.LOCK_NB)
except BlockingIOError as e:
    print("LOCK_NB:", type(e).__name__, e)
fcntl.flock(f, fcntl.LOCK_EX)   # without LOCK_NB: waits for the holder to exit
print("got the lock after waiting")
holder.wait()

Output:

LOCK_NB: BlockingIOError [Errno 11] Resource temporarily unavailable
got the lock after waiting

Measured: the same error comes from file locks. With LOCK_NB, flock() raises errno 11 at once when another process holds the lock; without it, the call waits. This is the usual way to stop a second copy of a cron script: catch BlockingIOError and exit.

4. Wait until the socket is ready instead of retrying

import selectors, socket, threading, time
a, b = socket.socketpair()
a.setblocking(False)
threading.Timer(0.3, lambda: b.send(b"late data")).start()
sel = selectors.DefaultSelector()
sel.register(a, selectors.EVENT_READ)
t = time.monotonic()
sel.select(timeout=2)          # wait until a is readable
print(f"readable after {time.monotonic() - t:.1f}s:", a.recv(1024))

Output:

readable after 0.3s: b'late data'

Measured: selectors blocks until the socket is readable (0.3 s here), then recv() succeeds. Use this instead of a while True: try recv retry loop. If you don't need non-blocking I/O, just leave the socket blocking with a timeout. More errno numbers in our errno codes list.

Written with AI assistance. Measured on 2026-10-09 with Python 3.13.5 on Linux: recv() on a non-blocking socketpair, settimeout(0.5) vs settimeout(0), fcntl.flock LOCK_NB against a second process, and selectors waiting for data. Every block was run verbatim and its output pasted from that run. PlainHeaders is our extension; everything else here is built-in Python.