pika/pika · error · ValueError

{name} must be >= 0, but got {value}

Error message

{name} must be >= 0, but got {value}

What it means

validators.zero_or_greater raises ValueError when an integer parameter is negative. It is used for AMQP QoS parameters: prefetch_size and prefetch_count in channel.basic_qos (channel.py:560-561). The AMQP spec requires these as non-negative integers, so pika guards before sending the frame. Note it casts with int(value), so non-numeric values raise their own TypeError/ValueError from int().

Source

Thrown at pika/validators.py:65

    if callable(callback):
        # nowait=False
        return False
    raise TypeError('completion callback must be callable if not None')


def zero_or_greater(name: str, value: int) -> None:
    """
    Verify that value is zero or greater.

    If not, 'name' will be used in error message

    :param name: value name to use in error message
    :param value: value to check
    :raises: ValueError
    """
    if int(value) < 0:
        errmsg = f'{name} must be >= 0, but got {value}'
        raise ValueError(errmsg)

View on GitHub (pinned to 295ad9e579)

Solutions

1. Clamp the computed value to max(0, desired) before calling basic_qos.
2. Use 0 for 'unlimited' prefetch, never a negative number.
3. Validate config-sourced prefetch values with an isinstance/>=0 check before passing them in.

Example fix

# before
channel.basic_qos(prefetch_count=capacity - in_flight)  # can be negative
# after
channel.basic_qos(prefetch_count=max(0, capacity - in_flight))

prefetch_count = max(0, int(prefetch_count))
prefetch_size = max(0, int(prefetch_size))
channel.basic_qos(prefetch_size=prefetch_size, prefetch_count=prefetch_count)

def is_nonneg_int(v: int) -> bool:
    return isinstance(v, int) and v >= 0

When it happens

Trigger: Calling channel.basic_qos(prefetch_count=-1) or channel.basic_qos(prefetch_size=-100). Any negative value for either prefetch parameter triggers it; prefetch_count=0 means unlimited and is allowed.

Common situations: Computing prefetch from a formula that can go negative (e.g. capacity - inflight when inflight > capacity); defaulting an unset config to -1 and forwarding it; misunderstanding that 0 means unlimited and using -1 to mean 'no limit'.

Related errors

• blocked_connection_timeout must be >= 0, but got {value!r}
• channel_max must be <= {pika.channel.MAX_CHANNELS} and > 0,
• connection_attempts must be > 0, but got {value!r}
• Min AMQP 0.9.1 Frame Size is {spec.FRAME_MIN_SIZE}, but got
• Max AMQP 0.9.1 Frame Size is {spec.FRAME_MAX_SIZE}, but got

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