redis/redis-py · error · DataError

XADD ref_policy must be one of: KEEPREF, DELREF, ACKED

Error message

XADD ref_policy must be one of: KEEPREF, DELREF, ACKED

What it means

Raised by xadd() when ref_policy is provided but is not one of KEEPREF, DELREF, or ACKED. The ref_policy governs how consumer-group PEL references are treated during XADD-driven trimming, and only those three literal values are accepted.

Source

Thrown at redis/commands/core.py:7025

            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:
                raise DataError(
                    "XADD idmp must be a tuple of (producer_id, idempotent_id)"
                )
            pieces.extend([b"IDMP", idmp[0], idmp[1]])
        if maxlen is not None:
            if not isinstance(maxlen, int) or maxlen < 0:
                raise DataError("XADD maxlen must be non-negative integer")
            pieces.append(b"MAXLEN")
            if approximate:

View on GitHub (pinned to da03cdc7e8)

Solutions

1. Use one of 'KEEPREF', 'DELREF', 'ACKED' exactly (uppercase), or omit ref_policy entirely.
2. Validate config-supplied policy values against the allowed set before calling xadd.
3. Remember ref_policy only takes effect alongside a trim (maxlen/minid).

Example fix

# before
await r.xadd('s', {'f':'v'}, maxlen=10, ref_policy='keepref')
# after
await r.xadd('s', {'f':'v'}, maxlen=10, ref_policy='KEEPREF')

VALID_REF_POLICIES = {'KEEPREF', 'DELREF', 'ACKED'}
def validate_xadd_ref_policy(policy):
    if policy is not None and policy not in VALID_REF_POLICIES:
        raise ValueError(f'ref_policy must be one of {VALID_REF_POLICIES}')
    return True

def is_valid_ref_policy(p) -> bool:
    return p is None or p in {'KEEPREF', 'DELREF', 'ACKED'}

When it happens

Trigger: Calling client.xadd(name, fields, maxlen=1000, ref_policy='keepref') (wrong case), ref_policy='random', or any value outside the allowed set while also trimming.

Common situations: Case mismatch; passing an invalid policy string from config; typo in the policy name.

Related errors

• XACKDEL ref_policy must be one of: KEEPREF, DELREF, ACKED
• Only one of ```maxlen``` or ```minid``` may be specified
• Only one of ```idmpauto``` or ```idmp``` may be specified
• IDMPAUTO and IDMP can only be used with id='*'
• 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/7a81acfda2ec1a9c.json. Report an issue: GitHub.