{"record":{"id":"ff31a4f1b17b40a2","repo":"python/cpython","slug":"getaddrinfo-host-r-returned-empty-list","errorCode":null,"errorMessage":"getaddrinfo({host!r}) returned empty list","messagePattern":"getaddrinfo\\((.+?)\\) returned empty list","errorType":"exception","errorClass":"OSError","httpStatus":null,"severity":"error","filePath":"Lib/asyncio/base_events.py","lineNumber":1539,"sourceCode":"\n    async def _ensure_resolved(self, address, *,\n                               family=0, type=socket.SOCK_STREAM,\n                               proto=0, flags=0, loop):\n        host, port = address[:2]\n        info = _ipaddr_info(host, port, family, type, proto, *address[2:])\n        if info is not None:\n            # \"host\" is already a resolved IP.\n            return [info]\n        else:\n            return await loop.getaddrinfo(host, port, family=family, type=type,\n                                          proto=proto, flags=flags)\n\n    async def _create_server_getaddrinfo(self, host, port, family, flags):\n        infos = await self._ensure_resolved((host, port), family=family,\n                                            type=socket.SOCK_STREAM,\n                                            flags=flags, loop=self)\n        if not infos:\n            raise OSError(f'getaddrinfo({host!r}) returned empty list')\n        return infos\n\n    async def create_server(\n            self, protocol_factory, host=None, port=None,\n            *,\n            family=socket.AF_UNSPEC,\n            flags=socket.AI_PASSIVE,\n            sock=None,\n            backlog=100,\n            ssl=None,\n            reuse_address=None,\n            reuse_port=None,\n            keep_alive=None,\n            ssl_handshake_timeout=None,\n            ssl_shutdown_timeout=None,\n            start_serving=True):\n        \"\"\"Create a TCP server.\n","sourceCodeStart":1521,"sourceCodeEnd":1557,"githubUrl":"https://github.com/python/cpython/blob/bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6/Lib/asyncio/base_events.py#L1521-L1557","documentation":"Raised by BaseEventLoop._create_server_getaddrinfo() — used by create_server() — when resolving a host/port for the listener yields an empty list. It is an OSError signalling that name resolution produced no usable records for the requested family/flags (default AI_PASSIVE).","triggerScenarios":"loop.create_server(factory, 'some.host', 8080) where the host resolves to no records for the allowed family; e.g. an IPv6-only name with family=AF_INET, or AI_PASSIVE filtering everything out on a broken resolver.","commonSituations":"Binding a server to a hostname in a container with broken DNS; specifying a hostname that only has AAAA records while forcing AF_INET; typo'd hostname that resolves to NXDOMAIN in some resolvers behaves as empty list rather than gaierror.","solutions":["Test resolution first: socket.getaddrinfo(host, port, family, socket.AI_PASSIVE) and inspect the result","Use explicit IP literals (127.0.0.1, ::1) or None for all interfaces to bypass DNS entirely","Align family= with the records that actually exist for the host; fix container/host DNS if records should exist"],"exampleFix":"# before\nserver = await loop.create_server(factory, 'api.example.com', 8443, family=socket.AF_INET)\n\n# after\nserver = await loop.create_server(factory, '127.0.0.1', 8443)  # literal, no DNS","handlingStrategy":"try-catch","validationCode":"infos = socket.getaddrinfo(host, port, family, socket.SOCK_STREAM, flags=socket.AI_PASSIVE)\nif not infos:\n    host = '0.0.0.0'  # or '::' — fall back to a literal bind","typeGuard":null,"tryCatchPattern":"try:\n    server = await loop.create_server(factory, host, port)\nexcept OSError as e:\n    if 'returned empty list' in str(e):\n        server = await loop.create_server(factory, None, port)  # all interfaces, no DNS\n    else:\n        raise","preventionTips":["Prefer IP literals or None for bind addresses in production configs","Smoke-test DNS resolution at startup before binding the server"],"tags":["asyncio","server","dns","getaddrinfo"],"backgroundTag":null,"analyzedSha":"bc6749cc3b5ae4a5e88a6cc2d5b3bebbe354eae6","analyzedAt":"2026-08-14T22:01:13.976Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}