go-redis/redis · error

redis: RESET is not allowed when client-side caching is enab

Error message

redis: RESET is not allowed when client-side caching is enabled

What it means

Returned when a client built-in client-side caching (CSC) is enabled and a RESET command is issued on a pooled connection. RESET tears down the connection's tracking state and downgrades it to RESP2, which would silently invalidate the CSC assumptions the client relies on (cache keys are namespaced per RESP3-tracked connection). The guard in baseClient.cscCommandError matches RESET by its leading args, so even raw Do(ctx,"RESET",...) and pipelines are rejected.

Source

Thrown at csc_integration.go:538

// 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
// connection to RESP2.
var errResetWithCSC = errors.New(
	"redis: RESET is not allowed when client-side caching is enabled")

// errSubscribeWithCSC rejects raw subscriptions on the ordinary pool. The
// typed Subscribe methods use dedicated PubSub connections and remain allowed.
var errSubscribeWithCSC = errors.New(
	"redis: SUBSCRIBE is not allowed on pooled connections when client-side caching is enabled")

// cscCommandError rejects commands that can make a pooled connection's state
// diverge from the assumptions used by CSC.
func (c *baseClient) cscCommandError(cmd Cmder) error {
	// The successful attachment signal is shared with derived clients.
	// initConn's internal command wrapper is exempt during library setup.
	if !c.cscTrackingRequested() || c.allowClientTracking {
		return nil
	}
	switch {
	case isClientTrackingCmd(cmd):
		return errClientTrackingWithCSC

View on GitHub (pinned to 36d97525cd)

Solutions

1. Remove the RESET call; go-redis manages connection lifecycle internally — use client.Close() and create a fresh client if you need a clean connection.
2. If you must reset, disable built-in CSC by leaving Options.ClientSideCache nil and manage CLIENT TRACKING yourself.
3. For connection-level health checks use client.Ping(ctx) instead of RESET.

Example fix

// before
client.Do(ctx, "RESET")
// after
client.Close()
client = redis.NewClient(opts)

// Don't issue RESET on a CSC-enabled client at all.
// If you must, verify CSC is off first (either field enables it):
opts := client.Options()
if opts.ClientSideCache == nil && opts.ClientSideCacheConfig == nil {
    client.Do(ctx, "RESET")
}

func isCSCEnabled(c *redis.Client) bool {
    o := c.Options()
    return o.ClientSideCache != nil || o.ClientSideCacheConfig != nil
}

err := client.Do(ctx, "RESET").Err()
if err != nil && strings.Contains(err.Error(), "RESET is not allowed") {
    // drop RESET; use Close()+recreate instead
    client.Close()
}

When it happens

Trigger: Calling client.Do(ctx, "RESET") or sending RESET through a pipeline on a *Client/*ClusterClient whose Options.ClientSideCache is non-nil. Also triggered by any Cmder whose first arg resolves to "reset" via cscCommandError -> isResetCmd.

Common situations: Borrowing a RESET call from another client library's recipe, health-check liveness probes that issue RESET, or migrating code to a CSC-enabled client without dropping the RESET handshake.

Related errors

• redis: SUBSCRIBE is not allowed on pooled connections when c
• invalid client type
• invalid notification format
• handler cannot be nil
• redis: got %d elements in the key-value array, wanted a mult

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