{"record":{"id":"909421d3e5033b7f","repo":"python/cpython","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":1047,"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":1029,"sourceCodeEnd":1065,"githubUrl":"https://github.com/python/cpython/blob/bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6/Lib/asyncio/base_events.py#L1029-L1065","documentation":"Raised inside asyncio's connection attempt loop (_connect_sock) when every candidate bind address for the requested address family failed to bind, or none of the resolved local addresses matched the remote's family. It is an OSError raised only when `local_addr` was given (or family-restricted resolution produced no usable local candidate), after all bind attempts have been exhausted.","triggerScenarios":"Calling loop.create_connection(..., local_addr=(ip, port)) where local_addr resolves only to AF_INET addresses while the destination resolves to AF_INET6 (or vice versa), so the 'for ... else' completes with no bind attempt having succeeded for that family.","commonSituations":"Pinning an outgoing interface with local_addr='127.0.0.1' while connecting to an IPv6-only host; dual-stack hosts where getaddrinfo ordering changed; containers where an interface has no address in the requested family.","solutions":["Make local_addr family-compatible with the target, e.g. use a local IPv6 address for IPv6 destinations.","Omit local_addr to let the OS choose the outgoing address, or resolve both families and pair them explicitly.","Pass family=socket.AF_INET (or AF_INET6) to create_connection so local and remote resolution agree."],"exampleFix":"// before\nawait loop.create_connection(proto, '2001:db8::1', 80, local_addr=('192.0.2.5', 0))\n\n// after\nawait loop.create_connection(proto, '2001:db8::1', 80, local_addr=('2001:db8::5', 0))","handlingStrategy":"fallback","validationCode":"import socket, ipaddress\n\ndef families_compatible(local_addr, host):\n    def fam(a):\n        try:\n            return ipaddress.ip_address(a).version == 6 and socket.AF_INET6 or socket.AF_INET\n        except ValueError:\n            return None\n    lf, hf = fam(local_addr[0]), fam(host)\n    return lf is None or hf is None or lf == hf","typeGuard":null,"tryCatchPattern":"try:\n    tp, pr = await loop.create_connection(proto, host, port, local_addr=la)\nexcept OSError as e:\n    if 'no matching local address' not in str(e):\n        raise\n    tp, pr = await loop.create_connection(proto, host, port)  # retry without pinning","preventionTips":["Pair local_addr family with the remote family explicitly when pinning interfaces.","Make local_addr optional config so you can drop it when the network changes.","On dual-stack services, prefer binding by IPv6 with v4-mapped addresses or letting the OS choose."],"tags":["asyncio","network","ipv6","dual-stack","oserror"],"backgroundTag":null,"analyzedSha":"bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6","analyzedAt":"2026-08-14T22:01:13.976Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}