{"record":{"id":"a83c310621fe1cec","repo":"redis/redis-py","slug":"socket-getaddrinfo-returned-an-empty-list","errorCode":null,"errorMessage":"socket.getaddrinfo returned an empty list","messagePattern":"socket\\.getaddrinfo returned an empty list","errorType":"exception","errorClass":"OSError","httpStatus":null,"severity":"critical","filePath":"redis/connection.py","lineNumber":1634,"sourceCode":"\n                return sock\n\n            except OSError as _:\n                err = _\n                if sock is not None:\n                    try:\n                        sock.shutdown(socket.SHUT_RDWR)  # ensure a clean close\n                    except OSError:\n                        pass\n                    sock.close()\n\n        if err is not None:\n            try:\n                raise err\n            finally:\n                # Ensure we clear local references to caught exceptions\n                err = None\n        raise OSError(\"socket.getaddrinfo returned an empty list\")\n\n    def _host_error(self):\n        return f\"{self.host}:{self.port}\"\n\n    @property\n    def host(self) -> str:\n        return self._host\n\n    @host.setter\n    def host(self, value: str):\n        self._host = value\n\n\nclass CacheProxyConnection(MaintNotificationsAbstractConnection, ConnectionInterface):\n    DUMMY_CACHE_VALUE = b\"foo\"\n    MIN_ALLOWED_VERSION = \"7.4.0\"\n    DEFAULT_SERVER_NAME = \"redis\"\n","sourceCodeStart":1616,"sourceCodeEnd":1652,"githubUrl":"https://github.com/redis/redis-py/blob/6a6b581b48225afa0b76912d1028c6035baee932/redis/connection.py#L1616-L1652","documentation":"Raised in _connect (connection.py:1634) when socket.getaddrinfo(self.host, self.port, ...) returns an empty list — the DNS resolver produced no usable address records for the host. This is distinct from getaddrinfo raising an exception; it means resolution 'succeeded' with zero candidates, so no socket could be created and OSError is raised.","triggerScenarios":"Connecting to a hostname that resolves to nothing (no A/AAAA records), a DNS server returning an empty answer, an SRV/CNAME with no target, or a malformed host string that getaddrinfo accepts but yields no SOCK_STREAM addresses.","commonSituations":"Typo in hostname; DNS not yet propagated for a new service; private DNS zone unreachable from the client host; service decommissioned; ephemeral hostname from a failed deploy; IPv6-only host with IPv4-only socket_type.","solutions":["Resolve the host yourself: python -c \"import socket; print(socket.getaddrinfo('host', 6379))\" to confirm DNS.","Use an IP address directly to bypass DNS and isolate the problem.","Fix DNS (correct name, reachable resolver, propagated record).","For cluster/sentinel, ensure all node hostnames resolve from the client.","Check socket_type isn't filtering out available families (e.g. forcing AF_INET on an IPv6-only host)."],"exampleFix":"# before\nr = redis.Redis(host='redis-svc.myco', port=6379)  # NXDOMAIN-ish\n# after\nr = redis.Redis(host='10.0.0.5', port=6379)  # verified IP","handlingStrategy":"validation","validationCode":"import socket\ndef resolvable(host, port=6379):\n    try:\n        return bool(socket.getaddrinfo(host, port, socket.SOCK_STREAM))\n    except socket.gaierror:\n        return False\n\nassert resolvable(h, p), f'no DNS records for {h}'\nr = redis.Redis(host=h, port=p)","typeGuard":"import socket\ndef is_resolvable(host: str, port: int = 6379) -> bool:\n    try:\n        return len(socket.getaddrinfo(host, port, socket.SOCK_STREAM)) > 0\n    except socket.gaierror:\n        return False","tryCatchPattern":"import socket\ntry:\n    r = redis.Redis(host=h, port=p); r.ping()\nexcept OSError as e:\n    if 'getaddrinfo' in str(e):\n        # fall back to a known IP or retry after DNS propagates\n        r = redis.Redis(host=ip_fallback, port=p)\n    else:\n        raise","preventionTips":["Resolve hostnames at startup and fail fast with a clear message.","Keep an IP fallback for critical paths.","Ensure the client host uses a DNS resolver that can see the private zone.","Verify all cluster/sentinel node names resolve."],"tags":["dns","network","connection","configuration"],"backgroundTag":null,"analyzedSha":"6a6b581b48225afa0b76912d1028c6035baee932","analyzedAt":"2026-08-10T12:52:44.840Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}