python/cpython · error · OSError

Connect call failed {address}

Error message

Connect call failed {address}

What it means

Raised as OSError(err, f'Connect call failed {address}') inside _sock_connect_cb: after a non-blocking connect completes, the callback reads the socket's SO_ERROR option, and a non-zero value means the kernel-level connection attempt failed (e.g. ECONNREFUSED, ENETUNREACH, ETIMEDOUT). The errno and target address are embedded in the message and it is delivered to the sock_connect() awaiter as the future's exception.

Source

Thrown at Lib/asyncio/selector_events.py:687

            fut.set_exception(exc)
        else:
            fut.set_result(None)
        finally:
            fut = None

    def _sock_write_done(self, fd, fut, handle=None):
        if handle is None or not handle.cancelled():
            self.remove_writer(fd)

    def _sock_connect_cb(self, fut, sock, address):
        if fut.done():
            return

        try:
            err = sock.getsockopt(socket.SOL_SOCKET, socket.SO_ERROR)
            if err != 0:
                # Jump to any except clause below.
                raise OSError(err, f'Connect call failed {address}')
        except (BlockingIOError, InterruptedError):
            # socket is still registered, the callback will be retried later
            pass
        except (SystemExit, KeyboardInterrupt):
            raise
        except BaseException as exc:
            fut.set_exception(exc)
        else:
            fut.set_result(None)
        finally:
            fut = None

    async def sock_accept(self, sock):
        """Accept a connection.

        The socket must be bound to an address and listening for
        connections.  The return value is a pair (conn, address) where
        conn is a new socket object usable to send and receive data on the

View on GitHub (pinned to bc6749cc3b)

Solutions

1. Verify the target address/port and that the remote service is listening (e.g. with ss -ltn or a manual check).
2. Wrap sock_connect in try/except OSError and handle ConnectionRefusedError specifically with retry-with-backoff for transient startup races.
3. Use asyncio.wait_for() to bound the connect attempt so kernel-level timeouts surface as asyncio timeouts you control.
4. Check firewall/security-group rules if connections to remote hosts consistently fail.

Example fix

// before
await loop.sock_connect(sock, addr)  # raises OSError: [Errno 111] Connect call failed ('127.0.0.1', 8080)

// after
try:
    await asyncio.wait_for(loop.sock_connect(sock, addr), timeout=5)
except ConnectionRefusedError:
    log.warning("server at %s not ready, retrying", addr)
    raise

def can_connect(addr):
    host, port = addr[:2]
    try:
        socket.getaddrinfo(host, port)
        return True
    except socket.gaierror:
        return False

for attempt in range(5):
    try:
        await asyncio.wait_for(loop.sock_connect(sock, addr), timeout=5)
        break
    except (ConnectionRefusedError, OSError) as e:
        if attempt == 4:
            raise
        await asyncio.sleep(2 ** attempt)

When it happens

Trigger: await loop.sock_connect(sock, address) where the remote refuses the connection (nothing listening on the port), the host is unreachable, routing fails, or the SYN times out at the OS level.

Common situations: Connecting to a service that is down or started later than the client; wrong port/IP in configuration; firewall silently dropping traffic leading to timeout variants; localhost tests where the server socket is not yet bound.

Related errors

• no matching local address with {family=} found
• getaddrinfo() returned empty list
• Multiple exceptions: {}
• data argument must be a bytes, bytearray, or memoryview obje
• Cannot call write() after write_eof()

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