python/cpython · error · ValueError

reuse_port not supported by socket module

Error message

reuse_port not supported by socket module

What it means

asyncio's _set_reuseport helper is invoked when reuse_port=True is passed to loop.create_server (or similar socket-creating APIs). It first checks whether the socket module even exposes SO_REUSEPORT; on platforms without it (notably Windows) it raises ValueError immediately, telling the caller the feature cannot be requested at all.

Source

Thrown at Lib/asyncio/base_events.py:94

    if isinstance(getattr(cb, '__self__', None), tasks.Task):
        # format the task
        return repr(cb.__self__)
    else:
        return str(handle)


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

View on GitHub (pinned to bc6749cc3b)

Solutions

1. Pass reuse_port=False (or omit it) on platforms without SO_REUSEPORT support.
2. Feature-detect before calling: use reuse_port=hasattr(socket, 'SO_REUSEPORT') and your platform policy.
3. On Windows, drop the multi-listener pattern that SO_REUSEPORT enables; use a single accepting process or an external load balancer.

Example fix

# before
server = await loop.create_server(handler, '0.0.0.0', 8080, reuse_port=True)
# on Windows -> ValueError: reuse_port not supported by socket module

# after
reuse = hasattr(socket, 'SO_REUSEPORT') and sys.platform != 'win32'
server = await loop.create_server(handler, '0.0.0.0', 8080, reuse_port=reuse)

import socket

def reuseport_available() -> bool:
    return hasattr(socket, 'SO_REUSEPORT')

try:
    server = await loop.create_server(h, host, port, reuse_port=True)
except ValueError as e:
    if 'reuse_port not supported' in str(e):
        server = await loop.create_server(h, host, port)  # retry without it

When it happens

Trigger: loop.create_server(handler, host, port, reuse_port=True) on Windows or any platform whose socket module lacks SO_REUSEPORT; also when a custom/limited socket shim (e.g. restricted embedded builds) hides the constant.

Common situations: Code developed on Linux (where SO_REUSEPORT enables multi-process port sharing) deployed to Windows services; containerized builds using minimal libc where the constant is compiled out; config files that unconditionally enable reuse_port across a heterogeneous fleet.

Related errors

• reuse_port not supported by socket module, SO_REUSEPORT defi
• 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/6fdd4f8bd5b4438d. Report an issue: GitHub.