redis/redis-py · critical · OSError

socket.getaddrinfo returned an empty list

Error message

socket.getaddrinfo returned an empty list

What it means

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.

Source

Thrown at redis/connection.py:1634

                return sock

            except OSError as _:
                err = _
                if sock is not None:
                    try:
                        sock.shutdown(socket.SHUT_RDWR)  # ensure a clean close
                    except OSError:
                        pass
                    sock.close()

        if err is not None:
            try:
                raise err
            finally:
                # Ensure we clear local references to caught exceptions
                err = None
        raise OSError("socket.getaddrinfo returned an empty list")

    def _host_error(self):
        return f"{self.host}:{self.port}"

    @property
    def host(self) -> str:
        return self._host

    @host.setter
    def host(self, value: str):
        self._host = value


class CacheProxyConnection(MaintNotificationsAbstractConnection, ConnectionInterface):
    DUMMY_CACHE_VALUE = b"foo"
    MIN_ALLOWED_VERSION = "7.4.0"
    DEFAULT_SERVER_NAME = "redis"

View on GitHub (pinned to 43bf5ac31a)

Solutions

1. Verify the hostname resolves from the runtime (getent hosts <host> / dig <host>).
2. Fix typos and ensure the DNS/VPC/private zone is reachable from the client process.
3. If forcing a socket family, ensure the hostname has records of that family, or pass an IP / allow the default family.
4. Retry transient DNS failures with a short backoff.

Example fix

# before
r = Redis(host='redis-prod', port=6379)
# after
import socket
socket.gethostbyname('redis-prod')  # verify first
r = Redis(host='redis-prod', port=6379,
          retry=Retry(ExponentialBackoff(), 3),
          retry_on_error=[ConnectionError, OSError])

import socket
def host_resolves(host):
    try:
        return len(socket.getaddrinfo(host, 6379)) > 0
    except socket.gaierror:
        return False

from redis.exceptions import ConnectionError, OSError
from redis.retry import Retry
from redis.backoff import ExponentialBackoff
r = Redis(host=h, retry=Retry(ExponentialBackoff(), 3),
          retry_on_error=[ConnectionError, OSError])
try:
    r.ping()
except OSError:
    # fix DNS / hostname config, then retry
    ...

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

• DNS resolution errors: ENOTFOUND and getaddrinfo failures — how hostname lookups fail and how to debug them.

Related errors

• Connection closed by server.
• Buffer is closed.
• Connection closed by server.
• Connection closed by server.
• Connection closed by server.

AI-assisted analysis of redis/redis-py@43bf5ac31a (2026-08-06). Data as JSON: /api/errors/a83c310621fe1cec. Report an issue: GitHub.