What causes "CLIENT PAUSE timeout must be an integer" in redis/redis-py?

Pass an int milliseconds value: r.client_pause(timeout=100)

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() (redis/commands/core.py:1240) when timeout is not a Python int (isinstance(timeout, int)). Note bool is a subclass of int so True/False pass through. Floats (e.g. 1.5) and numeric strings ('100') are rejected. This is a redis.exceptions.DataError raised client-side. Note the line ordering: str(timeout) is computed first but the DataError still propagates because raise is hit afterward.

Solutions

Pass an int milliseconds value: r.client_pause(timeout=100)
Convert string input: r.client_pause(timeout=int(config_value))
Round floats explicitly: r.client_pause(timeout=int(round(seconds * 1000)))

Example fix

# before
r.client_pause(timeout=os.environ["PAUSE_MS"])
# after
r.client_pause(timeout=int(os.environ["PAUSE_MS"]))

Defensive patterns

Strategy: validation

Validate before calling

if not isinstance(timeout, int) or isinstance(timeout, bool) and not isinstance(timeout, int):
    timeout = int(timeout)
if not isinstance(timeout, int):
    raise TypeError("timeout must be int")
r.client_pause(timeout)

Type guard

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

Try / catch

from redis.exceptions import DataError
try:
    r.client_pause(timeout)
except DataError as e:
    if "timeout must be an integer" in str(e):
        r.client_pause(int(timeout))
    else:
        raise

Prevention

Always pass timeout as an int (milliseconds).
Coerce string config values with int(...) at the boundary.
Round fractional seconds explicitly; do not pass floats.

When it happens

Trigger: Calling r.client_pause(timeout=1.5) (float), r.client_pause(timeout="100") (string), or a Decimal value. r.client_pause(timeout=100) is fine; r.client_pause(timeout=True) also passes due to bool subclassing int.

Common situations: Reading a timeout from an env var or JSON config yields a string; or computing a fractional-second pause; or passing a numpy int that is not a Python int.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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

Appendix: 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 6a6b581b48)