redis/redis-py · error · DataError

XCLAIM idle must be an integer

Error message

XCLAIM idle must be an integer

What it means

Raised by Redis.xclaim() when the optional idle argument is provided and is not an int. idle sets the message's idle time (last-delivered) in ms. Only checked when idle is not None. isinstance(int) is strict, so floats/strings fail.

Solutions

1. Pass an int milliseconds value for idle, or omit it.
2. Coerce: idle = int(idle_ms) before calling.

Example fix

# before
r.xclaim('s','g','c', 0, ['1-0'], idle=now - delivered)  # float

# after
r.xclaim('s','g','c', 0, ['1-0'], idle=int(now - delivered))

if idle is not None and not isinstance(idle, int):
    idle = int(idle)

lambda v: v is None or (isinstance(v, int) and not isinstance(v, bool))

from redis.exceptions import DataError
try:
    r.xclaim('s','g','c', 0, ids, idle=i)
except DataError as e:
    log.warning('bad xclaim idle %r: %s', i, e)

When it happens

Trigger: Calling r.xclaim(..., idle=1.5) or idle='100'. idle=None skips the check.

Common situations: Passing a fractional or stringified ms value from timing instrumentation.

Related errors

• XCLAIM min_idle_time must be a non negative integer
• XCLAIM retrycount must be an integer
• XCLAIM time must be an integer
• XCLAIM force must be a boolean
• XCLAIM justid must be a boolean

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

Appendix: source

Thrown at redis/commands/core.py:7306

        of messages successfully claimed, without returning the actual message

        For more information, see https://redis.io/commands/xclaim
        """
        if not isinstance(min_idle_time, int) or min_idle_time < 0:
            raise DataError("XCLAIM min_idle_time must be a non negative integer")
        if not isinstance(message_ids, (list, tuple)) or not message_ids:
            raise DataError(
                "XCLAIM message_ids must be a non empty list or "
                "tuple of message IDs to claim"
            )

        kwargs = {}
        pieces: list[EncodableT] = [name, groupname, consumername, str(min_idle_time)]
        pieces.extend(list(message_ids))

        if idle is not None:
            if not isinstance(idle, int):
                raise DataError("XCLAIM idle must be an integer")
            pieces.extend((b"IDLE", str(idle)))
        if time is not None:
            if not isinstance(time, int):
                raise DataError("XCLAIM time must be an integer")
            pieces.extend((b"TIME", str(time)))
        if retrycount is not None:
            if not isinstance(retrycount, int):
                raise DataError("XCLAIM retrycount must be an integer")
            pieces.extend((b"RETRYCOUNT", str(retrycount)))

        if force:
            if not isinstance(force, bool):
                raise DataError("XCLAIM force must be a boolean")
            pieces.append(b"FORCE")
        if justid:
            if not isinstance(justid, bool):
                raise DataError("XCLAIM justid must be a boolean")
            pieces.append(b"JUSTID")

View on GitHub (pinned to 6a6b581b48)