redis/redis-py · error · ConnectionError

ConnectionError(exc)

Error message

ConnectionError(exc)

What it means

ConnectionError raised as a catch-all in Connection.connect_check_health (redis/asyncio/connection.py:877). After socket-level errors (OSError) and timeouts are handled specifically, any remaining exception during connect/on_connect is wrapped in ConnectionError and re-raised. This preserves a consistent error type for unexpected connection-time failures (TLS handshake errors, SSL issues, decoder faults, etc.).

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 6a6b581b48)

Solutions

1. Inspect the chained __cause__ exception for the real underlying error
2. For TLS errors, verify ssl_ca_certs / ssl_certfile / ssl_keyfile / ssl_cert_reqs
3. If using a custom redis_connect_func, ensure it does not raise on healthy connections
4. Check auth/credential_provider setup and server reachability

# generic; verify TLS config and reachability first
if ssl and not os.path.exists(ca_path):
    raise ValueError('ca cert missing')

try:
    await client.ping()
except ConnectionError as e:
    cause = e.__cause__  # the real underlying error
    log.error('connect failed: %r', cause)

When it happens

Trigger: TLS/SSL handshake failures, errors thrown by a custom redis_connect_func, unexpected exceptions from on_connect (auth callback failures, parser init errors), or any non-OSError during connection establishment.

Common situations: TLS misconfiguration (bad cert, wrong CA); a custom redis_connect_func that raises; auth provider failures during the initial HELLO/AUTH; event-loop or transport errors.

Related errors

• Connection closed by server.
• Buffer is closed.
• Maintenance notifications are only supported with hiredis an
• To configure maintenance notifications, a parser must be pro
• Cannot enable maintenance notifications for connection objec

AI-assisted analysis of redis/redis-py@6a6b581b48 (2026-08-10). Data as JSON: /api/errors/4a3e0e645b97d200. Report an issue: GitHub.