{"record":{"id":"9b0a8c9e234bbeb2","repo":"python/cpython","slug":"getaddrinfo-returned-empty-list","errorCode":null,"errorMessage":"getaddrinfo() returned empty list","messagePattern":"getaddrinfo\\(\\) returned empty list","errorType":"exception","errorClass":"OSError","httpStatus":null,"severity":"error","filePath":"Lib/asyncio/base_events.py","lineNumber":1129,"sourceCode":"                'ssl_shutdown_timeout is only meaningful with ssl')\n\n        if sock is not None:\n            _check_ssl_socket(sock)\n\n        if happy_eyeballs_delay is not None and interleave is None:\n            # If using happy eyeballs, default to interleave addresses by family\n            interleave = 1\n\n        if host is not None or port is not None:\n            if sock is not None:\n                raise ValueError(\n                    'host/port and sock can not be specified at the same time')\n\n            infos = await self._ensure_resolved(\n                (host, port), family=family,\n                type=socket.SOCK_STREAM, proto=proto, flags=flags, loop=self)\n            if not infos:\n                raise OSError('getaddrinfo() returned empty list')\n\n            if local_addr is not None:\n                laddr_infos = await self._ensure_resolved(\n                    local_addr, family=family,\n                    type=socket.SOCK_STREAM, proto=proto,\n                    flags=flags, loop=self)\n                if not laddr_infos:\n                    raise OSError('getaddrinfo() returned empty list')\n            else:\n                laddr_infos = None\n\n            if interleave:\n                infos = _interleave_addrinfos(infos, interleave)\n\n            exceptions = []\n            if happy_eyeballs_delay is None:\n                # not using happy eyeballs\n                for addrinfo in infos:","sourceCodeStart":1111,"sourceCodeEnd":1147,"githubUrl":"https://github.com/python/cpython/blob/bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6/Lib/asyncio/base_events.py#L1111-L1147","documentation":"Raised as OSError by create_connection when getaddrinfo() for the target (host, port) returns an empty list. Normally getaddrinfo raises on failure, but with certain flag combinations or AI_ADDRCONFIG-style behavior it can succeed with zero results; asyncio then has no address to connect to and raises this.","triggerScenarios":"loop.create_connection(proto, host, port, flags=...) where the flags filter out all results (e.g. AI_ADDRCONFIG on a host family the machine lacks), or a resolver edge case returning [] for the requested family/type/proto combination.","commonSituations":"Passing custom flags copied from sync socket code; hosts whose only records are in a family the local machine cannot use (IPv6-only names on IPv4-only hosts with filtering resolvers); unusual NSS/resolver configurations in containers.","solutions":["Verify the host resolves at all: socket.getaddrinfo(host, port, type=SOCK_STREAM) in a REPL.","Drop custom flags and let asyncio use its defaults.","Check the host string for typos/scheme prefixes like 'https://example.com' passed as a bare host."],"exampleFix":"// before\nawait loop.create_connection(proto, 'https://example.com', 443)  # scheme left in host\n\n// after\nawait loop.create_connection(proto, 'example.com', 443)","handlingStrategy":"validation","validationCode":"import socket\ninfos = socket.getaddrinfo(host, port, type=socket.SOCK_STREAM)\nassert infos, f'{host!r} resolves to nothing for SOCK_STREAM'","typeGuard":null,"tryCatchPattern":"try:\n    tp, pr = await loop.create_connection(proto, host, port)\nexcept OSError as e:\n    if 'returned empty list' not in str(e):\n        raise\n    host = host.removeprefix('https://').removeprefix('http://').split('/')[0]\n    tp, pr = await loop.create_connection(proto, host, port)","preventionTips":["Strip schemes and paths from URLs before using them as hosts.","Pre-check resolution with socket.getaddrinfo when the name comes from user input.","Avoid custom flags on _ensure_resolved-driven calls unless you understand the filtering."],"tags":["asyncio","network","dns","oserror"],"backgroundTag":null,"analyzedSha":"bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6","analyzedAt":"2026-08-14T22:01:13.976Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}