{"record":{"id":"857eee01bca62f20","repo":"redis/redis-py","slug":"prefix-can-only-be-used-with-bcast","errorCode":null,"errorMessage":"Prefix can only be used with bcast","messagePattern":"Prefix can only be used with bcast","errorType":"exception","errorClass":"DataError","httpStatus":null,"severity":"error","filePath":"redis/commands/core.py","lineNumber":1101,"sourceCode":"        ``optin``  when broadcasting is NOT active, normally don't track\n        keys in read only commands, unless they are called immediately\n        after a CLIENT CACHING yes command.\n\n        ``optout`` when broadcasting is NOT active, normally track keys in\n        read only commands, unless they are called immediately after a\n        CLIENT CACHING no command.\n\n        ``noloop`` don't send notifications about keys modified by this\n        connection itself.\n\n        ``prefix``  for broadcasting, register a given key prefix, so that\n        notifications will be provided only for keys starting with this string.\n\n        See https://redis.io/commands/client-tracking\n        \"\"\"\n\n        if len(prefix) != 0 and bcast is False:\n            raise DataError(\"Prefix can only be used with bcast\")\n\n        pieces = [\"ON\"] if on else [\"OFF\"]\n        if clientid is not None:\n            pieces.extend([\"REDIRECT\", clientid])\n        for p in prefix:\n            pieces.extend([\"PREFIX\", p])\n        if bcast:\n            pieces.append(\"BCAST\")\n        if optin:\n            pieces.append(\"OPTIN\")\n        if optout:\n            pieces.append(\"OPTOUT\")\n        if noloop:\n            pieces.append(\"NOLOOP\")\n\n        return self.execute_command(\"CLIENT TRACKING\", *pieces, **kwargs)\n\n    @overload","sourceCodeStart":1083,"sourceCodeEnd":1119,"githubUrl":"https://github.com/redis/redis-py/blob/6a6b581b48225afa0b76912d1028c6035baee932/redis/commands/core.py#L1083-L1119","documentation":"Raised by client_tracking()/client_tracking_on()/client_tracking_off() (redis/commands/core.py:1101) when a non-empty prefix sequence is supplied but bcast is False. Per Redis semantics, PREFIX filters only apply in broadcasting mode, so the library rejects the combination rather than silently dropping the prefixes. This is a redis.exceptions.DataError raised before the command is sent.","triggerScenarios":"Calling r.client_tracking(prefix=[\"user:\"]) without bcast=True; or r.client_tracking_on(prefix=[b\"cache:\"]) (bcast defaults to False). Empty prefix [] with bcast=False is fine.","commonSituations":"Wanting prefix-scoped invalidation but forgetting that the server only honors prefixes in BCAST mode; copying a non-broadcast tracking example and adding a prefix.","solutions":["Enable broadcasting when you use prefixes: r.client_tracking(prefix=[\"user:\"], bcast=True)","If you want default (non-broadcast) tracking, remove the prefix argument entirely","Combine prefixes with redirect/noloop as needed once bcast=True is set"],"exampleFix":"# before\nr.client_tracking(prefix=[\"user:\"])\n# after\nr.client_tracking(prefix=[\"user:\"], bcast=True)","handlingStrategy":"validation","validationCode":"if prefix and not bcast:\n    raise ValueError(\"prefix requires bcast=True\")\nr.client_tracking(prefix=prefix, bcast=bcast or bool(prefix))","typeGuard":null,"tryCatchPattern":"from redis.exceptions import DataError\ntry:\n    r.client_tracking(prefix=prefix)\nexcept DataError as e:\n    if \"Prefix can only be used with bcast\" in str(e):\n        r.client_tracking(prefix=prefix, bcast=True)\n    else:\n        raise","preventionTips":["Treat prefix as a BCAST-only option.","When you want default (per-key) tracking, drop the prefix argument.","Add a unit test asserting prefix+non-bcast raises, to catch regressions."],"tags":["client-side-caching","validation","dataerror","tracking"],"backgroundTag":null,"analyzedSha":"6a6b581b48225afa0b76912d1028c6035baee932","analyzedAt":"2026-08-10T12:52:44.840Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}