{"record":{"id":"45dcc593a6f71fe2","repo":"RustPython/RustPython","slug":"no-matching-local-address-with-family-found","errorCode":null,"errorMessage":"no matching local address with {family=} found","messagePattern":"no matching local address with (.+?) found","errorType":"exception","errorClass":"OSError","httpStatus":null,"severity":"error","filePath":"Lib/asyncio/base_events.py","lineNumber":1041,"sourceCode":"                    for lfamily, _, _, _, laddr in local_addr_infos:\n                        # skip local addresses of different family\n                        if lfamily != family:\n                            continue\n                        try:\n                            sock.bind(laddr)\n                            break\n                        except OSError as exc:\n                            msg = (\n                                f'error while attempting to bind on '\n                                f'address {laddr!r}: {str(exc).lower()}'\n                            )\n                            exc = OSError(exc.errno, msg)\n                            my_exceptions.append(exc)\n                    else:  # all bind attempts failed\n                        if my_exceptions:\n                            raise my_exceptions.pop()\n                        else:\n                            raise OSError(f\"no matching local address with {family=} found\")\n                await self.sock_connect(sock, address)\n                return sock\n            except OSError as exc:\n                my_exceptions.append(exc)\n                raise\n        except:\n            if sock is not None:\n                try:\n                    sock.close()\n                except OSError:\n                    # An error when closing a newly created socket is\n                    # not important, but it can overwrite more important\n                    # non-OSError error. So ignore it.\n                    pass\n            raise\n        finally:\n            exceptions = my_exceptions = None\n","sourceCodeStart":1023,"sourceCodeEnd":1059,"githubUrl":"https://github.com/RustPython/RustPython/blob/aaeab4f754b4f40efc0c8ab39cf7c4a3c35a8cfd/Lib/asyncio/base_events.py#L1023-L1059","documentation":"Raised as OSError inside BaseEventLoop._connect_sock during create_connection when a local_addr was supplied and resolved, but none of the resolved local addresses share the socket family of the remote address currently being tried (the for/else branch with no recorded bind exceptions). It means the bind loop found no usable local endpoint for that address family.","triggerScenarios":"await loop.create_connection(proto, '2001:db8::1', 80, local_addr=('127.0.0.1', 0)) — IPv6 remote with IPv4-only local_addr; family=socket.AF_INET6 forced while local_addr resolves only to A records; dual-stack hosts where getaddrinfo for the local name returns only the other family.","commonSituations":"Hardcoding local_addr=('0.0.0.0', 0) or ('127.0.0.1', 0) for outbound multi-family connections; migrating a service to IPv6 while keeping an IPv4 bind address; DNS returning unexpected families for the local hostname.","solutions":["Drop local_addr entirely and let the OS pick the source address","Make local_addr family-compatible: use ('::', 0) for IPv6 remotes, ('0.0.0.0', 0) for IPv4 remotes","Pre-resolve the remote, then pick local_addr with socket.family matching addrinfo[0]"],"exampleFix":"# before\nawait loop.create_connection(proto, '2001:db8::1', 80, local_addr=('127.0.0.1', 0))\n\n# after\ninfos = await loop.getaddrinfo('2001:db8::1', 80, type=socket.SOCK_STREAM)\nlocal = ('::', 0) if infos[0][0] == socket.AF_INET6 else ('0.0.0.0', 0)\nawait loop.create_connection(proto, '2001:db8::1', 80, local_addr=local)","handlingStrategy":"validation","validationCode":"infos = await loop.getaddrinfo(host, port, type=socket.SOCK_STREAM)\nremote_family = infos[0][0]\nlocal = ('::', 0) if remote_family == socket.AF_INET6 else ('0.0.0.0', 0)\nawait loop.create_connection(proto, host, port, local_addr=local)","typeGuard":"def local_addr_matches_family(local_addr, family) -> bool:\n    if local_addr is None:\n        return True\n    host = local_addr[0]\n    try:\n        socket.inet_pton(family, host)\n        return True\n    except OSError:\n        return False","tryCatchPattern":"try:\n    tr, pr = await loop.create_connection(p, host, port, local_addr=la)\nexcept OSError as e:\n    if 'no matching local address' in str(e):\n        log.error('local_addr %r has no address in family of %r', la, host)\n        tr, pr = await loop.create_connection(p, host, port)  # retry unbound\n    else:\n        raise","preventionTips":["Prefer omitting local_addr unless you truly need a fixed egress IP","Pair IPv6 remotes with ('::', 0), IPv4 remotes with ('0.0.0.0', 0)","Resolve both ends and compare .family before calling create_connection"],"tags":["asyncio","network","ipv6","address-family","oserror"],"backgroundTag":"address-family-mismatch","analyzedSha":"aaeab4f754b4f40efc0c8ab39cf7c4a3c35a8cfd","analyzedAt":"2026-08-17T00:37:52.100Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}