redis/redis-py · error · DataError

idletimemust be an integer

Error message

idletimemust be an integer

What it means

restore() accepts an optional idletime eviction hint that must be an integer (seconds). The code calls int(idletime) inside a try/except ValueError at core.py:2777-2780 and converts it to DataError. Note the message has a missing space ('idletimemust be an integer') but the meaning is clear.

Source

Thrown at redis/commands/core.py:4280

        ``idletime`` Used for eviction, this is the number of seconds the
        key must be idle, prior to execution.

        ``frequency`` Used for eviction, this is the frequency counter of
        the object stored at the key, prior to execution.

        For more information, see https://redis.io/commands/restore
        """
        params = [name, ttl, value]
        if replace:
            params.append("REPLACE")
        if absttl:
            params.append("ABSTTL")
        if idletime is not None:
            params.append("IDLETIME")
            try:
                params.append(int(idletime))
            except ValueError:
                raise DataError("idletimemust be an integer")

        if frequency is not None:
            params.append("FREQ")
            try:
                params.append(int(frequency))
            except ValueError:
                raise DataError("frequency must be an integer")

        return self.execute_command("RESTORE", *params)

    @overload
    def set(
        self: SyncClientProtocol,
        name: KeyT,
        value: EncodableT,
        ex: ExpiryT | None = ...,
        px: ExpiryT | None = ...,
        nx: bool = ...,

View on GitHub (pinned to da03cdc7e8)

Solutions

1. Pass an int for idletime, e.g. r.restore('k', 0, blob, idletime=100).
2. Coerce and validate upstream: idletime = int(idletime) before calling restore().
3. Omit idletime entirely if you do not need to set an idle eviction hint.

Example fix

# before
r.restore('k', 0, blob, idletime=user_input)

# after
r.restore('k', 0, blob, idletime=int(user_input))

if idletime is not None:
    idletime = int(idletime)  # raises early if non-numeric
r.restore('k', 0, blob, idletime=idletime)

def is_int_like(v) -> bool:
    try:
        int(v)
        return True
    except (TypeError, ValueError):
        return False

from redis.exceptions import DataError
try:
    r.restore('k', 0, blob, idletime=idletime)
except DataError as e:
    if 'idletime' in str(e):
        r.restore('k', 0, blob, idletime=int(idletime))
    else:
        raise

When it happens

Trigger: r.restore('k', 0, blob, idletime='abc') or any non-numeric string for idletime. A float like 1.5 would succeed (int() truncates), but non-numeric strings fail.

Common situations: Forwarding unparsed config/CLI strings into restore(); deserialized DUMP payloads where idletime came back as a string.

Related errors

• frequency must be an integer
• Both start and end must be specified
• bit must be 0 or 1
• start argument is not set, when end is specified
• Only one of IFEQ/IFNE/IFDEQ/IFDNE may be specified

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