redis/go-redis · error

redis: CLIENT TRACKING is not allowed when client-side cachi

Error message

redis: CLIENT TRACKING is not allowed when client-side caching is enabled

What it means

When the client's built-in client-side caching (CSC) is enabled, the library forbids issuing CLIENT TRACKING — including raw Do(ctx, "client", "tracking", ...) escapes and pipelines — because the two invalidation mechanisms conflict. The guard in baseClient.process and generalProcessPipeline matches on the command's leading args and returns errClientTrackingWithCSC.

Source

Thrown at csc_integration.go:518

	}
	return 0
}

// cscForgetConn drops connID's init-generation entry when initialization does
// not establish tracked coverage, either because init failed or tracking was
// rejected and CSC was disabled.
func (c *baseClient) cscForgetConn(connID uint64) {
	if h := c.cscHook(); h != nil {
		h.forgetConn(connID)
	}
}

// errClientTrackingWithCSC rejects CLIENT TRACKING on clients with built-in CSC
// (see the guards in baseClient.process and generalProcessPipeline). The raw
// escape hatches — Do(ctx, "client", "tracking", ...) with string or []byte
// args, and pipelines — are also caught: the guard matches on the command's
// leading args, not the typed method.
var errClientTrackingWithCSC = errors.New(
	"redis: CLIENT TRACKING is not allowed when client-side caching is enabled")

// errSelectWithCSC rejects runtime SELECT on clients with built-in CSC. Cache
// keys use Options.DB, while SELECT mutates only the chosen pool connection.
var errSelectWithCSC = errors.New(
	"redis: SELECT is not allowed when client-side caching is enabled")

// errAuthWithCSC rejects runtime authentication because it can change one
// connection's ACL identity without changing the client's fixed cache namespace.
var errAuthWithCSC = errors.New(
	"redis: AUTH is not allowed when client-side caching is enabled")

// errHelloWithCSC rejects HELLO with arguments because it can switch a tracked
// connection out of RESP3 (and can also change authentication).
var errHelloWithCSC = errors.New(
	"redis: HELLO with arguments is not allowed when client-side caching is enabled")

// errResetWithCSC rejects RESET because it disables tracking and switches the

View on GitHub (pinned to c5cad058c7)

Solutions

1. Remove the CLIENT TRACKING call — built-in CSC manages tracking itself.
2. Disable built-in CSC in the client Options if you must control CLIENT TRACKING manually.
3. Search for raw Do() calls with "client" "tracking" args and pipelines issuing them, and delete them.

Example fix

// before
rdb.Do(ctx, "client", "tracking", "optin") // CSC-enabled client
// after
// built-in CSC handles tracking; remove the manual command, or
// disable built-in CSC in Options to manage tracking yourself

func clientTrackingAllowed(opts *redis.Options) bool {
    return !clientSideCachingEnabled(opts) // remove manual CLIENT TRACKING when CSC is on
}

if err := rdb.ClientTracking(ctx, opt).Err(); err != nil {
    if strings.Contains(err.Error(), "not allowed when client-side caching is enabled") {
        // drop the manual tracking call; built-in CSC owns tracking
    }
}

When it happens

Trigger: Calling rdb.ClientTracking(...) on a client whose Options enable built-in CSC; or bypassing the typed method with rdb.Do(ctx, "client", "tracking", "optin") or the same inside a pipeline on such a client.

Common situations: Migrating manual CLIENT TRACKING code to the built-in cache without removing the old tracking setup; enabling Options-level CSC while retaining middleware that issues CLIENT TRACKING at connect time.

Related errors

• redis: CLIENT TRACKING OPTIN and OPTOUT are mutually exclusi
• redis: CLIENT TRACKING BCAST cannot be combined with OPTIN o
• redis: CLIENT TRACKING PREFIX requires BCAST
• csc: a different "invalidate" push handler is already regist

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