pika/pika · error · ValueError

socket_timeout must be > 0, but got {value!r}

Error message

socket_timeout must be > 0, but got {value!r}

What it means

Raised by the `socket_timeout` setter (pika/connection.py:443) when a numeric value is <= 0. A non-positive connect timeout is meaningless (it would make every connect instantly fail), so pika rejects it after the type check. None is the documented way to disable the timeout, not 0.

Source

Thrown at pika/connection.py:443

        :returns: socket connect timeout in seconds. Defaults to
            `DEFAULT_SOCKET_TIMEOUT`. The value None disables this timeout.

        """
        return self._socket_timeout

    @socket_timeout.setter
    def socket_timeout(self, value: float | None) -> None:
        """
        :param value: positive socket connect timeout in
            seconds. None to disable this timeout.

        """
        if value is not None:
            if not isinstance(value, numbers.Real):
                raise TypeError('socket_timeout must be a float or int, '
                                f'but got {value!r}')
            if value <= 0:
                raise ValueError(
                    f'socket_timeout must be > 0, but got {value!r}')
            value = float(value)

        self._socket_timeout = value

    @property
    def stack_timeout(self) -> float | None:
        """
        :returns: full protocol stack TCP/[SSL]/AMQP bring-up timeout in
            seconds. Defaults to `DEFAULT_STACK_TIMEOUT`. The value None
            disables this timeout.

        """
        return self._stack_timeout

    @stack_timeout.setter
    def stack_timeout(self, value: float | None) -> None:
        """

View on GitHub (pinned to 295ad9e579)

Solutions

1. Pass `None` to disable the timeout, not 0.
2. Pick a positive value matched to your network (e.g. 5-10 seconds).
3. Clamp computed timeouts: `params.socket_timeout = timeout if timeout > 0 else None`.
4. Document in your config schema that 0 is invalid for this field.

Example fix

# before
params.socket_timeout = 0  # intended 'no timeout'
# after
params.socket_timeout = None

def parse_socket_timeout(v):
    if v is None:
        return None
    f = float(v)
    if f <= 0:
        raise ValueError(f'socket_timeout must be > 0, got {f}')
    return f
params.socket_timeout = parse_socket_timeout(raw)

import numbers
def is_positive_or_none(v) -> bool:
    return v is None or (isinstance(v, numbers.Real) and v > 0)

try:
    params.socket_timeout = raw
except ValueError:
    params.socket_timeout = None  # disable instead

When it happens

Trigger: `params.socket_timeout = 0`, `params.socket_timeout = -1`, or `ConnectionParameters(socket_timeout=0.0)`.

Common situations: Assuming 0 means 'no timeout' (common convention in other libraries), computing a timeout that underflows to 0, or inheriting a default from another tool that uses 0 as 'infinite'.

Related errors

• heartbeat must >= 0, but got {value!r}
• socket_timeout must be a float or int, but got {value!r}
• stack_timeout must be > 0, but got {value!r}
• heartbeat must be an int or a callable function, but got {va
• port must be an int, but got {value!r}

AI-assisted analysis of pika/pika@295ad9e579 (2026-08-04). Data as JSON: /data/errors/a6e9eab9252c995c.json. Report an issue: GitHub.