redis/redis-py · error · DataError

Only one of ```maxlen``` or ```minid``` may be specified

Error message

Only one of ```maxlen``` or ```minid``` may be specified

What it means

Raised by xadd() when both maxlen and minid are provided. MAXLEN trims the stream by length while MINID trims by ID; Redis only allows one trimming strategy per XADD, so the client rejects specifying both.

Source

Thrown at redis/commands/core.py:7016

            - DELREF: When trimming, removes all references from consumer groups' PEL
            - ACKED: When trimming, only removes entries acknowledged by all consumer groups
        idmpauto: Producer ID for automatic idempotent ID calculation.
            Automatically calculates an idempotent ID based on entry content to prevent
            duplicate entries. Can only be used with id='*'. Creates an IDMP map if it
            doesn't exist yet. The producer ID must be unique per producer and consistent
            across restarts.
        idmp: Tuple of (producer_id, idempotent_id) for explicit idempotent ID.
            Uses a specific idempotent ID to prevent duplicate entries. Can only be used
            with id='*'. The producer ID must be unique per producer and consistent across
            restarts. The idempotent ID must be unique per message and per producer.
            Shorter idempotent IDs require less memory and allow faster processing.
            Creates an IDMP map if it doesn't exist yet.

        For more information, see https://redis.io/commands/xadd
        """
        pieces: list[EncodableT] = []
        if maxlen is not None and minid is not None:
            raise DataError("Only one of ```maxlen``` or ```minid``` may be specified")

        if idmpauto is not None and idmp is not None:
            raise DataError("Only one of ```idmpauto``` or ```idmp``` may be specified")

        if (idmpauto is not None or idmp is not None) and id != "*":
            raise DataError("IDMPAUTO and IDMP can only be used with id='*'")

        if ref_policy is not None and ref_policy not in {"KEEPREF", "DELREF", "ACKED"}:
            raise DataError("XADD ref_policy must be one of: KEEPREF, DELREF, ACKED")

        if nomkstream:
            pieces.append(b"NOMKSTREAM")
        if ref_policy is not None:
            pieces.append(ref_policy)
        if idmpauto is not None:
            pieces.extend([b"IDMPAUTO", idmpauto])
        if idmp is not None:
            if not isinstance(idmp, tuple) or len(idmp) != 2:

View on GitHub (pinned to da03cdc7e8)

Solutions

1. Use maxlen for length-based trimming, or minid for ID-based trimming, but not both.
2. Decide on a single retention strategy per stream and pass only that argument.
3. If you need both behaviors, choose the stricter single strategy that satisfies your retention requirement.

Example fix

# before
await r.xadd('s', {'f': 'v'}, maxlen=1000, minid='1234-0')
# after
await r.xadd('s', {'f': 'v'}, maxlen=1000)

def validate_xadd_trim(maxlen, minid):
    if maxlen is not None and minid is not None:
        raise ValueError('Specify maxlen OR minid, not both')
    return True

When it happens

Trigger: Calling client.xadd(name, fields, maxlen=1000, minid='1234-0').

Common situations: Layering two trimming strategies; merging config that sets maxlen with code that sets minid; misunderstanding that they are alternative trim modes.

Related errors

• XADD maxlen must be non-negative integer
• Only one of ```idmpauto``` or ```idmp``` may be specified
• IDMPAUTO and IDMP can only be used with id='*'
• XADD ref_policy must be one of: KEEPREF, DELREF, ACKED
• XADD idmp must be a tuple of (producer_id, idempotent_id)

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