go-redis/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

Error "redis: CLIENT TRACKING is not allowed when client-side caching is enabled" thrown in go-redis/redis.

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 36d97525cd)

Solutions

1. Disable client-side caching (CacheSize/ttl options) if the application needs CLIENT TRACKING directly
2. Let go-redis manage tracking through its client-side caching integration instead of issuing CLIENT TRACKING manually

When it happens

Trigger: Thrown at csc_integration.go:518 when the library encounters an invalid state.

Common situations: Route all tracking configuration through the client's CSC options so manual CLIENT TRACKING calls are unnecessary.

AI-assisted analysis of go-redis/redis@36d97525cd (2026-08-06). Data as JSON: /data/errors/303c35da29fb7c27.json. Report an issue: GitHub.