python/cpython · error · OSError

no matching local address with {family=} found

Error message

no matching local address with {family=} found

What it means

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.

Source

Thrown at Lib/asyncio/base_events.py:1047

                    for lfamily, _, _, _, laddr in local_addr_infos:
                        # skip local addresses of different family
                        if lfamily != family:
                            continue
                        try:
                            sock.bind(laddr)
                            break
                        except OSError as exc:
                            msg = (
                                f'error while attempting to bind on '
                                f'address {laddr!r}: {str(exc).lower()}'
                            )
                            exc = OSError(exc.errno, msg)
                            my_exceptions.append(exc)
                    else:  # all bind attempts failed
                        if my_exceptions:
                            raise my_exceptions.pop()
                        else:
                            raise OSError(f"no matching local address with {family=} found")
                await self.sock_connect(sock, address)
                return sock
            except OSError as exc:
                my_exceptions.append(exc)
                raise
        except:
            if sock is not None:
                try:
                    sock.close()
                except OSError:
                    # An error when closing a newly created socket is
                    # not important, but it can overwrite more important
                    # non-OSError error. So ignore it.
                    pass
            raise
        finally:
            exceptions = my_exceptions = None

View on GitHub (pinned to bc6749cc3b)

Solutions

  1. Make local_addr family-compatible with the target, e.g. use a local IPv6 address for IPv6 destinations.
  2. Omit local_addr to let the OS choose the outgoing address, or resolve both families and pair them explicitly.
  3. Pass family=socket.AF_INET (or AF_INET6) to create_connection so local and remote resolution agree.

Example fix

// before
await loop.create_connection(proto, '2001:db8::1', 80, local_addr=('192.0.2.5', 0))

// after
await loop.create_connection(proto, '2001:db8::1', 80, local_addr=('2001:db8::5', 0))
Defensive patterns

Strategy: fallback

Validate before calling

import socket, ipaddress

def families_compatible(local_addr, host):
    def fam(a):
        try:
            return ipaddress.ip_address(a).version == 6 and socket.AF_INET6 or socket.AF_INET
        except ValueError:
            return None
    lf, hf = fam(local_addr[0]), fam(host)
    return lf is None or hf is None or lf == hf

Try / catch

try:
    tp, pr = await loop.create_connection(proto, host, port, local_addr=la)
except OSError as e:
    if 'no matching local address' not in str(e):
        raise
    tp, pr = await loop.create_connection(proto, host, port)  # retry without pinning

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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