redis/go-redis · error

redis: CLIENT TRACKING BCAST cannot be combined with OPTIN o

Error message

redis: CLIENT TRACKING BCAST cannot be combined with OPTIN or OPTOUT

What it means

Error returned by validateClientTrackingOptions (commands.go:631) when ClientTrackingOptions has Bcast set to true together with OptIn or OptOut. These modes are mutually exclusive in Redis's CLIENT TRACKING: BCAST broadcasts invalidation for all keys in the client's keyspace, while OPTIN/OPTOUT control per-key opt-in/opt-out tracking for a non-BCAST setup. Fix: either enable Bcast alone, or drop Bcast and use OptIn/OptOut.

Source

Thrown at commands.go:631

	cmd := NewStatusCmd(ctx, args...)
	_ = c(ctx, cmd)
	return cmd
}

// 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 {

View on GitHub (pinned to c5cad058c7)

Solutions

1. Remove OptIn/OptOut when using Bcast: true.
2. If per-key opt-in/out is needed, drop Bcast.
3. Remember PREFIX also requires BCAST.

Example fix

// before
rdb.ClientTracking(ctx, &redis.ClientTrackingOptions{Bcast: true, OptIn: true})
// after
rdb.ClientTracking(ctx, &redis.ClientTrackingOptions{Bcast: true})

func validTracking(o *redis.ClientTrackingOptions) bool {
    return o != nil && !(o.Bcast && (o.OptIn || o.OptOut))
}

if err := rdb.ClientTracking(ctx, opt).Err(); err != nil {
    if strings.Contains(err.Error(), "BCAST cannot be combined") {
        // clear OptIn/OptOut and retry
    }
}

When it happens

Trigger: Calling ClientTracking with ClientTrackingOptions{Bcast: true, OptIn: true} or {Bcast: true, OptOut: true}.

Common situations: Copying example code that used OPTIN and adding BCAST for broader invalidation; toggling Bcast on in config without clearing the opt flags.

Related errors

• redis: CLIENT TRACKING OPTIN and OPTOUT are mutually exclusi
• redis: CLIENT TRACKING PREFIX requires BCAST
• 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/43fd5fdb3a4c0e27. Report an issue: GitHub.