redis/redis-py · error · DataError

Prefix can only be used with bcast

Error message

Prefix can only be used with bcast

What it means

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.

Solutions

1. Enable broadcasting when you use prefixes: r.client_tracking(prefix=["user:"], bcast=True)
2. If you want default (non-broadcast) tracking, remove the prefix argument entirely
3. Combine prefixes with redirect/noloop as needed once bcast=True is set

Example fix

# before
r.client_tracking(prefix=["user:"])
# after
r.client_tracking(prefix=["user:"], bcast=True)

if prefix and not bcast:
    raise ValueError("prefix requires bcast=True")
r.client_tracking(prefix=prefix, bcast=bcast or bool(prefix))

from redis.exceptions import DataError
try:
    r.client_tracking(prefix=prefix)
except DataError as e:
    if "Prefix can only be used with bcast" in str(e):
        r.client_tracking(prefix=prefix, bcast=True)
    else:
        raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• bit must be 0 or 1
• Both start and end must be specified
• ``byfloat`` and ``byint`` are mutually exclusive.
• Cache must implement CacheInterface
• Cannot create cache key.

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

Appendix: source

Thrown at redis/commands/core.py:1101

        ``optin``  when broadcasting is NOT active, normally don't track
        keys in read only commands, unless they are called immediately
        after a CLIENT CACHING yes command.

        ``optout`` when broadcasting is NOT active, normally track keys in
        read only commands, unless they are called immediately after a
        CLIENT CACHING no command.

        ``noloop`` don't send notifications about keys modified by this
        connection itself.

        ``prefix``  for broadcasting, register a given key prefix, so that
        notifications will be provided only for keys starting with this string.

        See https://redis.io/commands/client-tracking
        """

        if len(prefix) != 0 and bcast is False:
            raise DataError("Prefix can only be used with bcast")

        pieces = ["ON"] if on else ["OFF"]
        if clientid is not None:
            pieces.extend(["REDIRECT", clientid])
        for p in prefix:
            pieces.extend(["PREFIX", p])
        if bcast:
            pieces.append("BCAST")
        if optin:
            pieces.append("OPTIN")
        if optout:
            pieces.append("OPTOUT")
        if noloop:
            pieces.append("NOLOOP")

        return self.execute_command("CLIENT TRACKING", *pieces, **kwargs)

    @overload

View on GitHub (pinned to 6a6b581b48)