{"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/43bf5ac31a5d7538fad3b1928e717ba757048041/redis/connection.py#L1616-L1652","documentation":"Raised by _connect (TCP connection setup) when socket.getaddrinfo returns an empty list for the configured host — i.e. DNS resolution produced no usable addresses. This is an OSError raised after exhausting (or having zero) address candidates, distinct from a name-resolution error which would surface differently.","triggerScenarios":"host is a hostname that resolves to nothing (NODATA / empty answer); a typo in the host; a hostname that only has records of an unsupported family given socket_type; transient DNS returning an empty answer.","commonSituations":"Misconfigured REDIS_HOST env var; private DNS not reachable from the runtime; service discovery returning empty; IPv6-only hostname with an IPv4-forced socket type.","solutions":["Verify the hostname resolves from the runtime (getent hosts <host> / dig <host>).","Fix typos and ensure the DNS/VPC/private zone is reachable from the client process.","If forcing a socket family, ensure the hostname has records of that family, or pass an IP / allow the default family.","Retry transient DNS failures with a short backoff."],"exampleFix":"# before\nr = Redis(host='redis-prod', port=6379)\n# after\nimport socket\nsocket.gethostbyname('redis-prod')  # verify first\nr = Redis(host='redis-prod', port=6379,\n          retry=Retry(ExponentialBackoff(), 3),\n          retry_on_error=[ConnectionError, OSError])","handlingStrategy":"retry","validationCode":"import socket\ndef host_resolves(host):\n    try:\n        return len(socket.getaddrinfo(host, 6379)) > 0\n    except socket.gaierror:\n        return False","typeGuard":null,"tryCatchPattern":"from redis.exceptions import ConnectionError, OSError\nfrom redis.retry import Retry\nfrom redis.backoff import ExponentialBackoff\nr = Redis(host=h, retry=Retry(ExponentialBackoff(), 3),\n          retry_on_error=[ConnectionError, OSError])\ntry:\n    r.ping()\nexcept OSError:\n    # fix DNS / hostname config, then retry\n    ...","preventionTips":["Verify hostname resolution from the runtime (getent hosts / dig).","Ensure private/VPC DNS is reachable from the client process.","Don't force a socket family that the hostname lacks records for.","Add connection retries for transient DNS flakiness."],"tags":["network","dns","connection","configuration"],"analyzedSha":"43bf5ac31a5d7538fad3b1928e717ba757048041","analyzedAt":"2026-08-06T22:35:38.048Z","schemaVersion":2},"datasetVersion":"2026-08-07T02:17:10.218Z"}