{"record":{"id":"7a81acfda2ec1a9c","repo":"redis/redis-py","slug":"xadd-ref-policy-must-be-one-of-keepref-delref-a","errorCode":null,"errorMessage":"XADD ref_policy must be one of: KEEPREF, DELREF, ACKED","messagePattern":"XADD ref_policy must be one of: KEEPREF, DELREF, ACKED","errorType":"validation","errorClass":"DataError","httpStatus":null,"severity":"error","filePath":"redis/commands/core.py","lineNumber":7025,"sourceCode":"            with id='*'. The producer ID must be unique per producer and consistent across\n            restarts. The idempotent ID must be unique per message and per producer.\n            Shorter idempotent IDs require less memory and allow faster processing.\n            Creates an IDMP map if it doesn't exist yet.\n\n        For more information, see https://redis.io/commands/xadd\n        \"\"\"\n        pieces: list[EncodableT] = []\n        if maxlen is not None and minid is not None:\n            raise DataError(\"Only one of ```maxlen``` or ```minid``` may be specified\")\n\n        if idmpauto is not None and idmp is not None:\n            raise DataError(\"Only one of ```idmpauto``` or ```idmp``` may be specified\")\n\n        if (idmpauto is not None or idmp is not None) and id != \"*\":\n            raise DataError(\"IDMPAUTO and IDMP can only be used with id='*'\")\n\n        if ref_policy is not None and ref_policy not in {\"KEEPREF\", \"DELREF\", \"ACKED\"}:\n            raise DataError(\"XADD ref_policy must be one of: KEEPREF, DELREF, ACKED\")\n\n        if nomkstream:\n            pieces.append(b\"NOMKSTREAM\")\n        if ref_policy is not None:\n            pieces.append(ref_policy)\n        if idmpauto is not None:\n            pieces.extend([b\"IDMPAUTO\", idmpauto])\n        if idmp is not None:\n            if not isinstance(idmp, tuple) or len(idmp) != 2:\n                raise DataError(\n                    \"XADD idmp must be a tuple of (producer_id, idempotent_id)\"\n                )\n            pieces.extend([b\"IDMP\", idmp[0], idmp[1]])\n        if maxlen is not None:\n            if not isinstance(maxlen, int) or maxlen < 0:\n                raise DataError(\"XADD maxlen must be non-negative integer\")\n            pieces.append(b\"MAXLEN\")\n            if approximate:","sourceCodeStart":7007,"sourceCodeEnd":7043,"githubUrl":"https://github.com/redis/redis-py/blob/6a6b581b48225afa0b76912d1028c6035baee932/redis/commands/core.py#L7007-L7043","documentation":"Raised by xadd() when ref_policy is not None and not one of KEEPREF, DELREF, or ACKED. ref_policy controls how consumer-group PEL references are handled during stream trimming on XADD; only those three tokens are valid. It is a DataError.","triggerScenarios":"Calling client.xadd('mystream', fields, ref_policy='keep') (wrong case), ref_policy='DELETE', or any string outside the allowed set.","commonSituations":"Lowercase/typo in the policy name, or forwarding an unvalidated user/config value.","solutions":["Pass ref_policy as exactly 'KEEPREF', 'DELREF', or 'ACKED' (uppercase), or leave it as None for default behavior.","Validate/normalize the value against the allowed set before calling xadd."],"exampleFix":"# before\nclient.xadd('s', {'f': 'v'}, maxlen=100, ref_policy='delref')\n\n# after\nclient.xadd('s', {'f': 'v'}, maxlen=100, ref_policy='DELREF')","handlingStrategy":"validation","validationCode":"VALID_REF_POLICIES = {'KEEPREF', 'DELREF', 'ACKED'}\nif ref_policy is not None and ref_policy not in VALID_REF_POLICIES:\n    raise ValueError(f'ref_policy must be one of {VALID_REF_POLICIES}')\nclient.xadd(name, fields, ref_policy=ref_policy)","typeGuard":"from typing import Literal\n\ndef is_valid_ref_policy(p: str | None) -> bool:\n    return p is None or p in {'KEEPREF', 'DELREF', 'ACKED'}\n\n# usage\nref_policy: Literal['KEEPREF', 'DELREF', 'ACKED'] | None = None","tryCatchPattern":"from redis.exceptions import DataError\ntry:\n    client.xadd(name, fields, ref_policy=ref_policy)\nexcept DataError as e:\n    if 'ref_policy' in str(e):\n        client.xadd(name, fields, ref_policy=None)","preventionTips":["Use Literal['KEEPREF','DELREF','ACKED'] | None as the type annotation for ref_policy.","Validate/normalize external config values before passing them to xadd."],"tags":["streams","xadd","ref-policy","validation","enum"],"backgroundTag":null,"analyzedSha":"6a6b581b48225afa0b76912d1028c6035baee932","analyzedAt":"2026-08-10T12:52:44.840Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}