redis/go-redis · error

redis: CLIENT TRACKING PREFIX requires BCAST

Error message

redis: CLIENT TRACKING PREFIX requires BCAST

What it means

Error returned by validateClientTrackingOptions (commands.go:634) when ClientTrackingOptions specifies one or more Prefixes but Bcast is not enabled. Redis only supports key-prefix patterns with CLIENT TRACKING in BCAST mode, since prefixes define a broadcast invalidation scope rather than specific keys. Fix: set Bcast: true in ClientTrackingOptions when using Prefixes.

Source

Thrown at commands.go:634

}

// ClientTrackingOff disables tracking on the serving connection. See
// ClientTracking for the pooled-client and built-in-CSC caveats.
func (c cmdable) ClientTrackingOff(ctx context.Context) *StatusCmd {
	cmd := NewStatusCmd(ctx, "client", "tracking", "off")
	_ = c(ctx, cmd)
	return cmd
}

func validateClientTrackingOptions(opt *ClientTrackingOptions) error {
	if opt.OptIn && opt.OptOut {
		return errors.New("redis: CLIENT TRACKING OPTIN and OPTOUT are mutually exclusive")
	}
	if opt.Bcast && (opt.OptIn || opt.OptOut) {
		return errors.New("redis: CLIENT TRACKING BCAST cannot be combined with OPTIN or OPTOUT")
	}
	if len(opt.Prefixes) > 0 && !opt.Bcast {
		return errors.New("redis: CLIENT TRACKING PREFIX requires BCAST")
	}
	return nil
}

func appendClientTrackingOptions(args []interface{}, opt *ClientTrackingOptions) []interface{} {
	if opt.Redirect != 0 {
		args = append(args, "redirect", opt.Redirect)
	}
	if opt.Bcast {
		args = append(args, "bcast")
	}
	for _, p := range opt.Prefixes {
		args = append(args, "prefix", p)
	}
	if opt.OptIn {
		args = append(args, "optin")
	}
	if opt.OptOut {

View on GitHub (pinned to c5cad058c7)

Solutions

1. Add Bcast: true to the options when specifying Prefixes.
2. Drop the Prefixes field if broadcast mode is not desired.
3. Validate options before the call.

Example fix

// before
rdb.ClientTracking(ctx, &redis.ClientTrackingOptions{Prefixes: []string{"user:"}})
// after
rdb.ClientTracking(ctx, &redis.ClientTrackingOptions{Bcast: true, Prefixes: []string{"user:"}})

func validTracking(o *redis.ClientTrackingOptions) bool {
    return o != nil && (len(o.Prefixes) == 0 || o.Bcast)
}

if err := rdb.ClientTracking(ctx, opt).Err(); err != nil {
    if strings.Contains(err.Error(), "PREFIX requires BCAST") {
        // add Bcast: true and retry
    }
}

When it happens

Trigger: Calling ClientTracking with ClientTrackingOptions{Prefixes: []string{"user:"}} and no Bcast: true.

Common situations: Trying targeted invalidation for key prefixes without realizing prefixes only work in broadcast mode; partially copying a BCAST example and omitting Bcast.

Related errors

• redis: CLIENT TRACKING OPTIN and OPTOUT are mutually exclusi
• redis: CLIENT TRACKING BCAST cannot be combined with OPTIN o
• both LibName and LibVer cannot be set at the same time
• at least one of LibName and LibVer should be set
• MemoryUsage expects single sample count

AI-assisted analysis of redis/go-redis@c5cad058c7 (2026-09-01). Data as JSON: /api/errors/2c3c68041199fd35. Report an issue: GitHub.