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 when a prefix is supplied but bcast is False (default). Key-prefix filtering in server-assisted client-side caching only makes sense in broadcast mode, where the server sends invalidations for keys matching the prefix regardless of what the connection reads.

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 da03cdc7e8)

Solutions

1. Set bcast=True whenever you supply prefix values.
2. If you don't want broadcast mode, remove the prefix argument entirely.
3. Verify that broadcast + prefix is the intended caching strategy (server pushes invalidations for those prefixes).

Example fix

# before
r.client_tracking(on=True, prefix=['cache:'])
# after
r.client_tracking(on=True, prefix=['cache:'], bcast=True)

if prefix and not bcast:
    raise ValueError('prefix requires bcast=True')

When it happens

Trigger: Calling r.client_tracking(on=True, prefix=['user:'], bcast=False). Passing a non-empty prefix list without setting bcast=True. Conditionally setting prefix but forgetting to toggle bcast.

Common situations: Enabling client-side caching with per-prefix scoping but omitting the bcast flag. Copying a tracking config where bcast was implied elsewhere. Migrating from an optin/optout setup that used prefixes incorrectly.

Related errors

• CLIENT KILL type must be one of {client_types!r}
• CLIENT KILL skipme must be a bool
• CLIENT KILL <filter> <value> ... ... <filter> <value> must s
• CLIENT LIST _type must be one of {client_types!r}
• client_id must be a list

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