redis/redis-py · error · DataError

CLIENT PAUSE timeout must be an integer

Error message

CLIENT PAUSE timeout must be an integer

What it means

Raised by client_pause when timeout is not an int. The value is str()'d into the command args, so a float or string would produce a malformed value. Note: the isinstance check happens AFTER str(timeout) is already concatenated, so the args list is built from whatever type was passed before the guard fires.

Source

Thrown at redis/commands/core.py:1240

        For more information, see https://redis.io/commands/client-pause

        Args:
            timeout: milliseconds to pause clients
            all: If true (default) all client commands are blocked.
                 otherwise, clients are only blocked if they attempt to execute
                 a write command.

        For the WRITE mode, some commands have special behavior:

        * EVAL/EVALSHA: Will block client for all scripts.
        * PUBLISH: Will block client.
        * PFCOUNT: Will block client.
        * WAIT: Acknowledgments will be delayed, so this command will
            appear blocked.
        """
        args = ["CLIENT PAUSE", str(timeout)]
        if not isinstance(timeout, int):
            raise DataError("CLIENT PAUSE timeout must be an integer")
        if not all:
            args.append("WRITE")
        return self.execute_command(*args, **kwargs)

    @overload
    def client_unpause(self: SyncClientProtocol, **kwargs) -> bytes | str: ...

    @overload
    def client_unpause(
        self: AsyncClientProtocol, **kwargs
    ) -> Awaitable[bytes | str]: ...

    def client_unpause(self, **kwargs) -> (bytes | str) | Awaitable[bytes | str]:
        """
        Unpause all redis clients

        For more information, see https://redis.io/commands/client-unpause
        """

View on GitHub (pinned to da03cdc7e8)

Solutions

1. Pass an int: r.client_pause(timeout=1000).
2. Coerce explicitly: client_pause(timeout=int(my_value)).
3. If computing from seconds, round or truncate to an integer millisecond value first.

Example fix

# before
r.client_pause(timeout=500.0)
# after
r.client_pause(timeout=500)

if not isinstance(timeout, int):
    timeout = int(timeout)
# now safe

def is_pause_timeout(v) -> bool:
    return isinstance(v, int) and not isinstance(v, bool)

When it happens

Trigger: Calling r.client_pause(timeout=5.0) with a float. Passing timeout='1000' as a string. Passing a timedelta or Decimal object.

Common situations: Timeout read from config as a float (e.g., seconds parsed from YAML). Division/multiplication producing a float where an int was expected. Passing milliseconds computed from a float expression.

Related errors

• CLIENT KILL skipme must be a bool
• client_id must be a list
• CLIENT KILL type must be one of {client_types!r}
• CLIENT KILL <filter> <value> ... ... <filter> <value> must s
• CLIENT LIST _type must be one of {client_types!r}

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