redis/redis-py · error · ConnectionError

protocol must be either 2 or 3

Error message

protocol must be either 2 or 3

What it means

Raised as a ConnectionError when the protocol integer is outside the supported range [2, 3]. The library only speaks RESP2 and RESP3, so any other integer (0, 1, 4, ...) is rejected at construction time. Unlike a non-numeric value, this passes int() but fails the bounds check.

Source

Thrown at redis/connection.py:929

        self.health_check_interval = health_check_interval
        self.next_health_check = 0
        self.redis_connect_func = redis_connect_func
        self.encoder = Encoder(encoding, encoding_errors, decode_responses)
        self.handshake_metadata = None
        self._sock = None
        self._socket_read_size = socket_read_size
        self._connect_callbacks = []
        self._buffer_cutoff = 6000
        self._re_auth_token: Optional[TokenInterface] = None
        try:
            p = int(protocol)
        except TypeError:
            p = DEFAULT_RESP_VERSION
        except ValueError:
            raise ConnectionError("protocol must be an integer")
        else:
            if p < 2 or p > 3:
                raise ConnectionError("protocol must be either 2 or 3")
        self.protocol = p
        self.legacy_responses = legacy_responses
        if self.protocol == 3 and parser_class == _RESP2Parser:
            # If the protocol is 3 but the parser is RESP2, change it to RESP3
            # This is needed because the parser might be set before the protocol
            # or might be provided as a kwarg to the constructor
            # We need to react on discrepancy only for RESP2 and RESP3
            # as hiredis supports both
            parser_class = _RESP3Parser
        self.set_parser(parser_class)

        self._command_packer = self._construct_command_packer(command_packer)
        self._should_reconnect = False

        # HIMPORT client-side state. `himport_registry` is the shared client-level
        # registry (empty if unconfigured) and persists across reconnects.
        self.himport_registry = himport_registry
        self._reset_himport_state()

View on GitHub (pinned to da03cdc7e8)

Solutions

1. Use protocol=2 (RESP2) or protocol=3 (RESP3), the only supported values.
2. Omit the argument entirely to use the default RESP3.
3. Fix any calculation that produces an out-of-range protocol number.

Example fix

// before
r = redis.Redis(protocol=4)
// after
r = redis.Redis(protocol=3)

def validate_protocol(p):
    p = int(p)
    if p not in (2, 3):
        raise ValueError('protocol must be 2 or 3')
    return p
protocol = validate_protocol(raw_protocol)

try:
    r = redis.Redis(host=h, protocol=raw_protocol)
except redis.exceptions.ConnectionError as e:
    if 'either 2 or 3' in str(e):
        raw_protocol = 3
        r = redis.Redis(host=h, protocol=raw_protocol)

When it happens

Trigger: Passing protocol=4, protocol=1, protocol=0, or a negative number to redis.Redis(protocol=...). Computing a protocol value dynamically that lands outside 2-3.

Common situations: Forward-looking config set to a not-yet-supported version; off-by-one in code that derives the protocol number; copying examples that assume a wider range.

Related errors

• protocol must be an integer
• Maintenance notifications handlers on connection are only su
• Maintenance notifications are only supported with RESP versi
• Maintenance notifications handlers on connection are only su
• HELLO is intentionally not implemented in the client.

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