{"record":{"id":"bf704f16ac82a6c0","repo":"python/cpython","slug":"create-connection-failed","errorCode":null,"errorMessage":"create_connection failed","messagePattern":"create_connection failed","errorType":"exception","errorClass":"ExceptionGroup","httpStatus":null,"severity":"error","filePath":"Lib/asyncio/base_events.py","lineNumber":1172,"sourceCode":"            else:  # using happy eyeballs\n                sock = (await staggered.staggered_race(\n                    (\n                        # can't use functools.partial as it keeps a reference\n                        # to exceptions\n                        lambda addrinfo=addrinfo: self._connect_sock(\n                            exceptions, addrinfo, laddr_infos\n                        )\n                        for addrinfo in infos\n                    ),\n                    happy_eyeballs_delay,\n                    loop=self,\n                ))[0]  # can't use sock, _, _ as it keeks a reference to exceptions\n\n            if sock is None:\n                exceptions = [exc for sub in exceptions for exc in sub]\n                try:\n                    if all_errors:\n                        raise ExceptionGroup(\"create_connection failed\", exceptions)\n                    if len(exceptions) == 1:\n                        raise exceptions[0]\n                    elif exceptions:\n                        # If they all have the same str(), raise one.\n                        model = str(exceptions[0])\n                        if all(str(exc) == model for exc in exceptions):\n                            raise exceptions[0]\n                        # Raise a combined exception so the user can see all\n                        # the various error messages.\n                        raise OSError('Multiple exceptions: {}'.format(\n                            ', '.join(str(exc) for exc in exceptions)))\n                    else:\n                        # No exceptions were collected, raise a timeout error\n                        raise TimeoutError('create_connection failed')\n                finally:\n                    exceptions = None\n\n        else:","sourceCodeStart":1154,"sourceCodeEnd":1190,"githubUrl":"https://github.com/python/cpython/blob/bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6/Lib/asyncio/base_events.py#L1154-L1190","documentation":"The message of the ExceptionGroup raised by create_connection (Python 3.11+ with all_errors=True, or 3.12+ where all_errors defaults True) when every connection attempt failed. Each attempted address contributed one exception; asyncio groups them so the caller can inspect all root causes (DNS, refused, timeouts) rather than just the first. The group itself is an ExceptionGroup, not an OSError.","triggerScenarios":"loop.create_connection(..., all_errors=True) to a multi-address host (dual-stack A+AAAA) where both the IPv6 and IPv4 attempts fail — e.g. firewall drops v6 (timeout) and v4 gets ECONNREFUSED. Catching OSError alone will NOT catch this ExceptionGroup.","commonSituations":"Upgrading to Python 3.12 where all_errors defaulted to True changed exception types; servers reachable on only one family; flaky networks where different attempts fail differently.","solutions":["Catch ExceptionGroup (or use except* syntax) and inspect .exceptions for root causes.","Pass all_errors=False to get legacy behavior (single exception or combined OSError), if compatibility matters.","Retry at a higher level with backoff once you have logged the per-address causes."],"exampleFix":"// before\ntry:\n    await loop.create_connection(proto, host, port)\nexcept OSError as e:  # misses ExceptionGroup on 3.12+\n    log(e)\n\n// after\ntry:\n    await loop.create_connection(proto, host, port)\nexcept* OSError as eg:\n    for exc in eg.exceptions:\n        log(f'attempt failed: {exc!r}')","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    tp, pr = await loop.create_connection(proto, host, port)\nexcept* OSError as eg:\n    for exc in eg.exceptions:\n        log.warning(f'connect attempt failed: {exc!r}')\n    raise\nexcept ExceptionGroup as eg:\n    for exc in eg.exceptions:\n        log.warning(f'connect attempt failed: {exc!r}')\n    raise","preventionTips":["On Python 3.12+, expect ExceptionGroup from create_connection and catch with except* or bare ExceptionGroup.","Set all_errors=False explicitly if your error handling assumes OSError.","Log eg.exceptions individually to diagnose per-address failures."],"tags":["asyncio","network","exception-group","python312","connection"],"backgroundTag":null,"analyzedSha":"bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6","analyzedAt":"2026-08-14T22:01:13.976Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}