redis/redis-py · error · DataError

XCFGSET idmp_duration must be an integer between 1 and 300

Error message

XCFGSET idmp_duration must be an integer between 1 and 300

What it means

Raised by Redis.xcfgset() when the idmp_duration argument is not a Python int, or falls outside the allowed range [1, 300]. idmp_duration is the idempotency window duration (seconds) tracked for stream commands; the client validates it before sending XCFGSET to the server. Passing None skips the check entirely.

Solutions

Pass an int within [1, 300], e.g. idmp_duration=10.
If the value comes from config/env, coerce it first: idmp_duration=int(value) and clamp into range.
Do not pass fractional seconds; round to the nearest whole second within bounds.

Example fix

# before
r.xcfgset('mystream', idmp_duration=1.5)

# after
r.xcfgset('mystream', idmp_duration=2)
# or, from config:
r.xcfgset('mystream', idmp_duration=max(1, min(300, int(cfg['idmp_duration']))))

Defensive patterns

Strategy: validation

Validate before calling

def valid_idmp_duration(v):
    return v is None or (isinstance(v, int) and not isinstance(v, bool) and 1 <= v <= 300)

if not valid_idmp_duration(idmp_duration):
    raise ValueError('idmp_duration must be int in [1,300]')

Type guard

lambda v: v is None or (isinstance(v, int) and not isinstance(v, bool) and 1 <= v <= 300)

Try / catch

from redis.exceptions import DataError
try:
    r.xcfgset('mystream', idmp_duration=dur)
except DataError as e:
    # fix the config source, do not retry unchanged
    log.warning('bad idmp_duration %r: %s', dur, e)

Prevention

Treat idmp_duration as a bounded integer at the config boundary, not at the call site.
Remember bool is a subclass of int in Python; reject it explicitly if it matters.

When it happens

Trigger: Calling r.xcfgset('mystream', idmp_duration=<v>) where <v> is a float (1.5), a numeric string ('10'), bool False (==0), or an int outside 1..300 such as 0, -1, or 301. The guard is `not isinstance(idmp_duration, int) or v < 1 or v > 300`.

Common situations: Loading the value from an env var or config file (arrives as str), using a float to express fractional seconds, or an off-by-one on the upper bound (300).

Related errors

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

Appendix: source

Thrown at redis/commands/core.py:7122

        Returns:
            OK on success.

        For more information, see https://redis.io/commands/xcfgset
        """
        if idmp_duration is None and idmp_maxsize is None:
            raise DataError(
                "XCFGSET requires at least one of idmp_duration or idmp_maxsize"
            )

        pieces: list[EncodableT] = []

        if idmp_duration is not None:
            if (
                not isinstance(idmp_duration, int)
                or idmp_duration < 1
                or idmp_duration > 300
            ):
                raise DataError(
                    "XCFGSET idmp_duration must be an integer between 1 and 300"
                )
            pieces.extend([b"IDMP-DURATION", idmp_duration])

        if idmp_maxsize is not None:
            if (
                not isinstance(idmp_maxsize, int)
                or idmp_maxsize < 1
                or idmp_maxsize > 1000000
            ):
                raise DataError(
                    "XCFGSET idmp_maxsize must be an integer between 1 and 1,000,000"
                )
            pieces.extend([b"IDMP-MAXSIZE", idmp_maxsize])

        return self.execute_command("XCFGSET", name, *pieces)

    @overload

View on GitHub (pinned to 6a6b581b48)