python/cpython · error · ValueError

socket modifier keyword arguments can not be used when sock

Error message

socket modifier keyword arguments can not be used when sock is specified. ({problems})

What it means

Raised by create_datagram_endpoint() when a pre-created socket (sock=) is supplied together with address-modifying keyword arguments such as local_addr, remote_addr, family, proto, flags, reuse_port, or allow_broadcast. When you supply the socket you fully control its configuration, so the loop refuses to double-configure it; the message lists the offending kwargs.

Source

Thrown at Lib/asyncio/base_events.py:1407

                                       local_addr=None, remote_addr=None, *,
                                       family=0, proto=0, flags=0,
                                       reuse_port=None,
                                       allow_broadcast=None, sock=None):
        """Create datagram connection."""
        if sock is not None:
            if sock.type == socket.SOCK_STREAM:
                raise ValueError(
                    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)

View on GitHub (pinned to bc6749cc3b)

Solutions

1. Remove the address/modifier kwargs and configure the socket yourself (bind it, set options) before passing sock=
2. Or drop sock= and let the loop create the socket from local_addr/remote_addr/family/etc.

Example fix

# before
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
sock.bind(('0.0.0.0', 9999))
await loop.create_datagram_endpoint(factory, sock=sock, local_addr=('0.0.0.0', 9999))

# after
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
sock.bind(('0.0.0.0', 9999))
await loop.create_datagram_endpoint(factory, sock=sock)

DATAGRAM_MODIFIERS = ('local_addr', 'remote_addr', 'family', 'proto', 'flags', 'reuse_port', 'allow_broadcast')
if sock is not None:
    conflicts = [k for k in DATAGRAM_MODIFIERS if locals().get(k)]
    assert not conflicts, f'remove {conflicts} when passing sock=',

When it happens

Trigger: loop.create_datagram_endpoint(factory, sock=sock, local_addr=('0.0.0.0', 9999)) or any combination of sock= with a truthy value among local_addr/remote_addr/family/proto/flags/reuse_port/allow_broadcast.

Common situations: Migrating code from address-based to socket-based creation and leaving the old local_addr/remote_addr kwargs in place; templates that set family=socket.AF_INET 'for safety' on all endpoints.

Related errors

• Unimplemented ioctl request
• A datagram socket was expected, got {sock!r}
• unexpected address family
• 2-tuple is expected
• data argument must be a bytes-like object, not {type(data)._

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