redis/redis-py · error · DataError

XAUTOCLAIM min_idle_time must be a nonnegative integer

Q: What causes "XAUTOCLAIM min_idle_time must be a nonnegative integer" in redis/redis-py?

Pass a non-negative integer for min_idle_time (milliseconds).

Error message

XAUTOCLAIM min_idle_time must be a nonnegative integer

What it means

Raised by Redis.xautoclaim() when min_idle_time is coercible to int and the result is negative. Note the check is `int(min_idle_time) < 0` wrapped in try/except TypeError, so values that cannot be int()-converted are silently passed through to the server rather than rejected here. Only a negative coerced value triggers this DataError.

Solutions

Pass a non-negative integer for min_idle_time (milliseconds).
Guard the value: min_idle_time = max(0, int(min_idle_time)).
If the value may be a string, coerce and clamp before the call.

Example fix

# before
r.xautoclaim('s', 'g', 'c', min_idle_time=delta)  # delta = -1

# after
r.xautoclaim('s', 'g', 'c', min_idle_time=max(0, int(delta)))

Defensive patterns

Strategy: validation

Validate before calling

if min_idle_time is not None and int(min_idle_time) < 0:
    raise ValueError('min_idle_time must be >= 0')
min_idle_time = int(min_idle_time)

Type guard

lambda v: v is None or (isinstance(v, (int, str)) and int(v) >= 0)

Try / catch

from redis.exceptions import DataError
try:
    r.xautoclaim('s','g','c', min_idle_time=t)
except DataError as e:
    log.warning('bad min_idle_time %r: %s', t, e)

Prevention

Coerce and clamp min_idle_time to >= 0 at the call site.
This guard only catches negatives; non-integer junk slips through to the server, so validate type yourself.

When it happens

Trigger: Calling r.xautoclaim(name, group, consumer, min_idle_time=-1) or a string like '-5' (int('-5') == -5). A non-coercible value like 'abc' does NOT raise here (TypeError is swallowed) and is forwarded to the server.

Common situations: Sign error computing idle delta, or reusing a 'delay' variable that can go negative.

Related errors

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

Appendix: source

Thrown at redis/commands/core.py:7194

        criteria. Conceptually, equivalent to calling XPENDING and then XCLAIM,
        but provides a more straightforward way to deal with message delivery
        failures via SCAN-like semantics.
        name: name of the stream.
        groupname: name of the consumer group.
        consumername: name of a consumer that claims the message.
        min_idle_time: filter messages that were idle less than this amount of
        milliseconds.
        start_id: filter messages with equal or greater ID.
        count: optional integer, upper limit of the number of entries that the
        command attempts to claim. Set to 100 by default.
        justid: optional boolean, false by default. Return just an array of IDs
        of messages successfully claimed, without returning the actual message

        For more information, see https://redis.io/commands/xautoclaim
        """
        try:
            if int(min_idle_time) < 0:
                raise DataError(
                    "XAUTOCLAIM min_idle_time must be a nonnegative integer"
                )
        except TypeError:
            pass

        kwargs = {}
        pieces = [name, groupname, consumername, min_idle_time, start_id]

        try:
            if int(count) < 0:
                raise DataError("XPENDING count must be a integer >= 0")
            pieces.extend([b"COUNT", count])
        except TypeError:
            pass
        if justid:
            pieces.append(b"JUSTID")
            kwargs["parse_justid"] = True

View on GitHub (pinned to 6a6b581b48)