python/cpython · error · ValueError

unexpected address family

Error message

unexpected address family

What it means

Raised by create_datagram_endpoint() when neither local_addr nor remote_addr is given and family is left at its default 0 (AF_UNSPEC). Without an address there is no way to infer the address family, so the loop requires you to state it explicitly via family=.

Source

Thrown at Lib/asyncio/base_events.py:1415

                    f'A datagram socket was expected, got {sock!r}')
            if (local_addr or remote_addr or
                    family or proto or flags or
                    reuse_port or allow_broadcast):
                # show the problematic kwargs in exception msg
                opts = dict(local_addr=local_addr, remote_addr=remote_addr,
                            family=family, proto=proto, flags=flags,
                            reuse_port=reuse_port,
                            allow_broadcast=allow_broadcast)
                problems = ', '.join(f'{k}={v}' for k, v in opts.items() if v)
                raise ValueError(
                    f'socket modifier keyword arguments can not be used '
                    f'when sock is specified. ({problems})')
            sock.setblocking(False)
            r_addr = None
        else:
            if not (local_addr or remote_addr):
                if family == 0:
                    raise ValueError('unexpected address family')
                addr_pairs_info = (((family, proto), (None, None)),)
            elif hasattr(socket, 'AF_UNIX') and family == socket.AF_UNIX:
                for addr in (local_addr, remote_addr):
                    if addr is not None and not isinstance(addr, str):
                        raise TypeError('string is expected')

                if local_addr and local_addr[0] not in (0, '\x00'):
                    try:
                        if stat.S_ISSOCK(os.stat(local_addr).st_mode):
                            os.remove(local_addr)
                    except FileNotFoundError:
                        pass
                    except OSError as err:
                        # Directory may have permissions only to create socket.
                        logger.error('Unable to check or remove stale UNIX '
                                     'socket %r: %r',
                                     local_addr, err)

View on GitHub (pinned to bc6749cc3b)

Solutions

1. Pass family explicitly, e.g. family=socket.AF_INET or family=socket.AF_INET6, when creating an unconnected endpoint
2. Or supply local_addr/remote_addr so the family is derived from DNS resolution

Example fix

# before
transport, _ = await loop.create_datagram_endpoint(factory)

# after
transport, _ = await loop.create_datagram_endpoint(factory, family=socket.AF_INET)

import socket
if sock is None and not local_addr and not remote_addr:
    assert family != 0, 'pass family=socket.AF_INET/AF_INET6 for unconnected datagram endpoints'

When it happens

Trigger: loop.create_datagram_endpoint(factory) with no local_addr, no remote_addr, and family left as 0; or family=0 passed explicitly with no addresses.

Common situations: Creating an unconnected datagram socket for sendto() use and forgetting to name the family; refactoring code that previously had remote_addr set.

Related errors

• Unimplemented ioctl request
• A datagram socket was expected, got {sock!r}
• socket modifier keyword arguments can not be used when sock
• 2-tuple is expected
• can not get address information

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