redis/redis-py · error · DataError

XCLAIM time must be an integer

Error message

XCLAIM time must be an integer

What it means

Raised by Redis.xclaim() when the optional time argument is provided and is not an int. time sets idle to an absolute Unix-ms timestamp (unlike idle which is relative). Strict isinstance(int); floats/strings fail.

Solutions

1. Pass an int Unix-ms timestamp for time, or omit it.
2. Coerce: time = int(time.time() * 1000).

Example fix

# before
r.xclaim('s','g','c', 0, ['1-0'], time=time.time() * 1000)  # float

# after
import time
r.xclaim('s','g','c', 0, ['1-0'], time=int(time.time() * 1000))

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

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, time=t)
except DataError as e:
    log.warning('bad xclaim time %r: %s', t, e)

When it happens

Trigger: Calling r.xclaim(..., time=int(time.time()*1000)) where the expression is a float, or time='1690000000000'.

Common situations: Forgetting to wrap time.time()*1000 in int(), or passing a datetime string.

Related errors

• XCLAIM idle must be an integer
• XCLAIM min_idle_time must be a non negative integer
• XCLAIM retrycount 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/5d1c1ab2a6c8a8b1. Report an issue: GitHub.

Appendix: source

Thrown at redis/commands/core.py:7310

        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")
            kwargs["parse_justid"] = True
        return self.execute_command("XCLAIM", *pieces, **kwargs)

    @overload

View on GitHub (pinned to 6a6b581b48)