redis/redis-py · error · ConnectionError

{exc}

Error message

{exc}

What it means

Catch-all in AbstractConnection.connect: any unexpected exception during socket connect/dispatch that is not already a RedisError, timeout, or OSError is re-raised as ConnectionError(exc) from exc. The message is the str() of the underlying exception, so the real cause is preserved in __cause__ and in the message text.

Source

Thrown at redis/asyncio/connection.py:878

                error_type=e,
                retry_attempts=actual_retry_attempts,
                is_internal=False,
            )
            raise e
        except OSError as e:
            e = ConnectionError(self._error_message(e))
            await record_error_count(
                server_address=getattr(self, "host", None),
                server_port=getattr(self, "port", None),
                network_peer_address=getattr(self, "host", None),
                network_peer_port=getattr(self, "port", None),
                error_type=e,
                retry_attempts=actual_retry_attempts,
                is_internal=False,
            )
            raise e
        except Exception as exc:
            raise ConnectionError(exc) from exc

        try:
            if not self.redis_connect_func:
                # Use the default on_connect function
                await self.on_connect_check_health(check_health=check_health)
            else:
                # Use the passed function redis_connect_func
                (
                    await self.redis_connect_func(self)
                    if asyncio.iscoroutinefunction(self.redis_connect_func)
                    else self.redis_connect_func(self)
                )
        except RedisError:
            # clean up after any error in on_connect
            await self.disconnect()
            raise

        # run any user callbacks. right now the only internal callback

View on GitHub (pinned to da03cdc7e8)

Solutions

1. Read __cause__ (or the message text) to identify the wrapped exception and address THAT specifically.
2. For SSL/TLS issues, verify ssl_ca_certs / ssl_cert_reqs / ssl_check_hostname against your server.
3. For DNS/connectivity, verify host/port reachability and that the event loop is running.
4. If using redis_connect_func, ensure it does not raise on success and surfaces clear errors on failure.

Example fix

// before
try:
    await client.ping()
except ConnectionError as e:
    print(e)  # opaque wrapped message
// after
try:
    await client.ping()
except ConnectionError as e:
    logging.exception('connect failed: %s', e.__cause__)

from redis.exceptions import ConnectionError
try:
    await client.ping()
except ConnectionError as e:
    logger.error('connect failed, underlying cause: %r', e.__cause__)
    # branch on isinstance(e.__cause__, ssl.SSLError | OSError | ...)

When it happens

Trigger: Any non-OSError, non-RedisError failure during connect()/on_connect — e.g. SSL errors, gaierror subclasses not caught earlier, unexpected parser failures, asyncio stream errors, etc.

Common situations: TLS/SNI misconfiguration; DNS failures that surface as a non-OSError; custom redis_connect_func raising; parser/encoder issues during handshake; asyncio loop closures.

Related errors

• Python wasn't built with SSL support
• Invalid SSL Certificate Requirements Flag: {ssl_cert_reqs}
• ocsp validation error
• Connection closed by server.
• Buffer is closed.

AI-assisted analysis of redis/redis-py@da03cdc7e8 (2026-08-04). Data as JSON: /data/errors/f467b0ae3936e13b.json. Report an issue: GitHub.