redis/redis-py · error · DataError

XREAD max_count must be a positive integer

Error message

XREAD max_count must be a positive integer

What it means

Raised by xread() when the max_count argument is not an int or is less than 1. max_count is a cumulative cap across all streams (distinct from per-stream count) and requires Redis >= 8.10.0. If both count and max_count are set, max_count must be >= count (a separate DataError is raised otherwise).

Source

Thrown at redis/commands/core.py:7918

                  may still be returned. Must be a positive integer. Requires
                  Redis >= 8.10.0.

        For more information, see https://redis.io/commands/xread
        """
        pieces = []
        if block is not None:
            if not isinstance(block, int) or block < 0:
                raise DataError("XREAD block must be a non-negative integer")
            pieces.append(b"BLOCK")
            pieces.append(str(block))
        if count is not None:
            if not isinstance(count, int) or count < 1:
                raise DataError("XREAD count must be a positive integer")
            pieces.append(b"COUNT")
            pieces.append(str(count))
        if max_count is not None:
            if not isinstance(max_count, int) or max_count < 1:
                raise DataError("XREAD max_count must be a positive integer")
            if count is not None and max_count < count:
                raise DataError(
                    "XREAD max_count must be greater than or equal to count"
                )
            pieces.append(b"MAXCOUNT")
            pieces.append(str(max_count))
        if max_size is not None:
            if not isinstance(max_size, int) or max_size < 1:
                raise DataError("XREAD max_size must be a positive integer")
            pieces.append(b"MAXSIZE")
            pieces.append(str(max_size))
        if not isinstance(streams, dict) or len(streams) == 0:
            raise DataError("XREAD streams must be a non empty dict")
        pieces.append(b"STREAMS")
        keys, values = zip(*streams.items())
        pieces.extend(keys)
        pieces.extend(values)
        response = self.execute_command("XREAD", *pieces, keys=keys)

View on GitHub (pinned to da03cdc7e8)

Solutions

1. Pass an int >= 1 for max_count.
2. Verify Redis server version >= 8.10.0 before using MAXCOUNT/MAXSIZE.
3. Ensure max_count >= count when both are set.
4. Coerce: max_count = int(max_count) if max_count else None.

Example fix

// before
client.xread({"s": "0"}, count=10, max_count="50")
// after
client.xread({"s": "0"}, count=10, max_count=50)

def normalize_max_count(v, count=None):
    if v is None:
        return None
    if not isinstance(v, int) or isinstance(v, bool):
        raise TypeError(f"max_count must be int, got {type(v)}")
    if v < 1:
        raise ValueError(f"max_count must be >= 1, got {v}")
    if count is not None and v < count:
        raise ValueError(f"max_count ({v}) must be >= count ({count})")
    return v

# also confirm server version supports MAXCOUNT (Redis >= 8.10.0)
info = client.info("server")
if tuple(int(x) for x in info["redis_version"].split(".")[:2]) < (8, 10):
    raise RuntimeError("MAXCOUNT requires Redis >= 8.10.0")

def is_positive_int(v) -> bool:
    return isinstance(v, int) and not isinstance(v, bool) and v >= 1

from redis.exceptions import DataError
try:
    client.xread({"s": "0"}, count=count, max_count=max_count)
except DataError as e:
    if "XREAD max_count" in str(e) and "greater than" not in str(e):
        client.xread({"s": "0"}, count=count, max_count=int(max_count))
    else:
        raise

When it happens

Trigger: Call client.xread(streams, max_count=...) with a non-int, zero, or negative value. Also requires a Redis server >= 8.10.0 to be meaningful at runtime; older servers will reject the MAXCOUNT option.

Common situations: Assuming max_count is supported on an older Redis (server then returns a syntax error); passing the same float-typed variable for both count and max_count; feeding a string from config.

Related errors

• XREAD block must be a non-negative integer
• XREAD count must be a positive integer
• XRANGE count must be a positive integer
• CLIENT KILL type must be one of {client_types!r}
• CLIENT KILL skipme must be a bool

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