python/cpython · error · ValueError

reuse_port not supported by socket module, SO_REUSEPORT defi

Error message

reuse_port not supported by socket module, SO_REUSEPORT defined but not implemented.

What it means

The second failure branch of _set_reuseport: the socket module defines SO_REUSEPORT, so asyncio attempts sock.setsockopt(SOL_SOCKET, SO_REUSEPORT, 1), but the kernel rejects it with OSError (commonly ENOPROTOOPT/EINVAL when the constant exists in headers yet the kernel or the address family does not implement it). asyncio converts that OSError into ValueError with the 'defined but not implemented' wording.

Source

Thrown at Lib/asyncio/base_events.py:99

def _format_pipe(fd):
    if fd == subprocess.PIPE:
        return '<pipe>'
    elif fd == subprocess.STDOUT:
        return '<stdout>'
    else:
        return repr(fd)


def _set_reuseport(sock):
    if not hasattr(socket, 'SO_REUSEPORT'):
        raise ValueError('reuse_port not supported by socket module')
    else:
        try:
            sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEPORT, 1)
        except OSError:
            raise ValueError('reuse_port not supported by socket module, '
                             'SO_REUSEPORT defined but not implemented.')


def _ipaddr_info(host, port, family, type, proto, flowinfo=0, scopeid=0):
    # Try to skip getaddrinfo if "host" is already an IP. Users might have
    # handled name resolution in their own code and pass in resolved IPs.
    if not hasattr(socket, 'inet_pton'):
        return

    if proto not in {0, socket.IPPROTO_TCP, socket.IPPROTO_UDP} or \
            host is None:
        return None

    if type == socket.SOCK_STREAM:
        proto = socket.IPPROTO_TCP
    elif type == socket.SOCK_DGRAM:
        proto = socket.IPPROTO_UDP
    else:

View on GitHub (pinned to bc6749cc3b)

Solutions

1. Omit reuse_port or pass False where kernel support is absent (containers/WSL1/older kernels).
2. Probe once at startup: try creating a throwaway socket and setting SO_REUSEPORT; enable the flag only if it succeeds.
3. Upgrade the kernel / run the service in a normal Linux environment when multi-listener port sharing is a hard requirement.

Example fix

# before
server = await loop.create_server(handler, None, 8080, reuse_port=True)
# kernel refuses setsockopt -> ValueError: ... defined but not implemented.

# after
def reuseport_ok():
    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
    try:
        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEPORT, 1)
        return True
    except OSError:
        return False
    finally:
        s.close()

server = await loop.create_server(handler, None, 8080, reuse_port=reuseport_ok())

import socket

def reuseport_works() -> bool:
    """Constant present AND the kernel actually honors it."""
    if not hasattr(socket, 'SO_REUSEPORT'):
        return False
    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
    try:
        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEPORT, 1)
        return True
    except OSError:
        return False
    finally:
        s.close()

try:
    server = await loop.create_server(h, host, port, reuse_port=True)
except ValueError as e:
    if 'SO_REUSEPORT defined but not implemented' in str(e):
        log.warning('kernel lacks SO_REUSEPORT; continuing without it')
        server = await loop.create_server(h, host, port)

When it happens

Trigger: reuse_port=True with AF_INET6 sockets on kernels lacking IPv6 SO_REUSEPORT support; running inside containers or sandboxes (seccomp, some WSL1 configurations) where the setsockopt is blocked; odd BSD variants where the option requires specific socket types; running under an environment where capabilities deny the option.

Common situations: Deploying Linux-developed asyncio services to older kernels, minimal VMs, or WSL1; CI runners whose seccomp profile blocks uncommon socket options; multi-worker server templates that hardcode reuse_port=True.

Related errors

• reuse_port not supported by socket module
• Socket cannot be of type SSLSocket
• host/port and sock can not be specified at the same time
• A Stream Socket was expected, got {sock!r}
• Failed to fetch glossary.json

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