{"record":{"id":"859a56359965790f","repo":"python/cpython","slug":"reuse-port-not-supported-by-socket-module-so-reus","errorCode":null,"errorMessage":"reuse_port not supported by socket module, SO_REUSEPORT defined but not implemented.","messagePattern":"reuse_port not supported by socket module, SO_REUSEPORT defined but not implemented\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"Lib/asyncio/base_events.py","lineNumber":99,"sourceCode":"\n\ndef _format_pipe(fd):\n    if fd == subprocess.PIPE:\n        return '<pipe>'\n    elif fd == subprocess.STDOUT:\n        return '<stdout>'\n    else:\n        return repr(fd)\n\n\ndef _set_reuseport(sock):\n    if not hasattr(socket, 'SO_REUSEPORT'):\n        raise ValueError('reuse_port not supported by socket module')\n    else:\n        try:\n            sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEPORT, 1)\n        except OSError:\n            raise ValueError('reuse_port not supported by socket module, '\n                             'SO_REUSEPORT defined but not implemented.')\n\n\ndef _ipaddr_info(host, port, family, type, proto, flowinfo=0, scopeid=0):\n    # Try to skip getaddrinfo if \"host\" is already an IP. Users might have\n    # handled name resolution in their own code and pass in resolved IPs.\n    if not hasattr(socket, 'inet_pton'):\n        return\n\n    if proto not in {0, socket.IPPROTO_TCP, socket.IPPROTO_UDP} or \\\n            host is None:\n        return None\n\n    if type == socket.SOCK_STREAM:\n        proto = socket.IPPROTO_TCP\n    elif type == socket.SOCK_DGRAM:\n        proto = socket.IPPROTO_UDP\n    else:","sourceCodeStart":81,"sourceCodeEnd":117,"githubUrl":"https://github.com/python/cpython/blob/bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6/Lib/asyncio/base_events.py#L81-L117","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Omit reuse_port or pass False where kernel support is absent (containers/WSL1/older kernels).","Probe once at startup: try creating a throwaway socket and setting SO_REUSEPORT; enable the flag only if it succeeds.","Upgrade the kernel / run the service in a normal Linux environment when multi-listener port sharing is a hard requirement."],"exampleFix":"# before\nserver = await loop.create_server(handler, None, 8080, reuse_port=True)\n# kernel refuses setsockopt -> ValueError: ... defined but not implemented.\n\n# after\ndef reuseport_ok():\n    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\n    try:\n        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEPORT, 1)\n        return True\n    except OSError:\n        return False\n    finally:\n        s.close()\n\nserver = await loop.create_server(handler, None, 8080, reuse_port=reuseport_ok())","handlingStrategy":"validation","validationCode":"import socket\n\ndef reuseport_works() -> bool:\n    \"\"\"Constant present AND the kernel actually honors it.\"\"\"\n    if not hasattr(socket, 'SO_REUSEPORT'):\n        return False\n    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\n    try:\n        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEPORT, 1)\n        return True\n    except OSError:\n        return False\n    finally:\n        s.close()","typeGuard":null,"tryCatchPattern":"try:\n    server = await loop.create_server(h, host, port, reuse_port=True)\nexcept ValueError as e:\n    if 'SO_REUSEPORT defined but not implemented' in str(e):\n        log.warning('kernel lacks SO_REUSEPORT; continuing without it')\n        server = await loop.create_server(h, host, port)","preventionTips":["Probe setsockopt on a throwaway socket at startup instead of trusting the constant's existence.","Make reuse_port an opt-in config flag, not a default, for services deployed in containers/WSL.","Log and continue without the option rather than crashing listeners in heterogeneous fleets."],"tags":["asyncio","sockets","so-reuseport","kernel-support","containers"],"backgroundTag":null,"analyzedSha":"bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6","analyzedAt":"2026-08-14T22:01:13.976Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}