Smart Client Handoffs: Reduce Disconnects During Upgrades and Maintenance – Redis Knowledge Base

Redis Cloud and Redis Software experience short-lived disconnects and elevated latency during planned upgrades, node replacements, database version changes, shard migrations, and failovers. Smart client handoffs (SCH) reduces these disruptions by allowing clients to pre-connect to replacement nodes and temporarily relax timeouts during maintenance.
This article covers Symptoms, Root Cause, How SCH Works, Upgrade Scenarios, Prerequisites, Operational Checklist, and Troubleshooting.

Quick Fix Table

Symptom	Fast Check	Recommended Action
Short disconnects during maintenance	Does the client support SCH + RESP3?	Upgrade client library and enable RESP3; SCH will pre-handoff and relax timeouts.
Timeouts during upgrades	Is SCH enabled on server? Does client allow relaxed timeouts?	Enable SCH on Redis Software clusters; ensure client supports adaptive timeouts.
SCH not triggered	Is Redis version ≥7.2 and cluster ≥8.0.2?	Upgrade Redis Software cluster; confirm RESP3 is enabled.
In-place upgrade still disconnects	In-place replaces node processes	Use rolling upgrade for near-seamless transitions; brief drops are expected otherwise.

Symptoms

Brief disconnects during maintenance windows (typically seconds).

Example:

Redis error: Error 61 connecting to localhost:6379. Connection refused.

Increased latency and occasional timeouts during node or database upgrades. Example:

Redis error: Timeout reading from socket

Root Cause

Maintenance operations temporarily alter node availability or shard routing:

In-place upgrades restart Redis node processes, interrupting active connections.
Rolling upgrades add replacement nodes and migrate traffic; clients must reconnect.
Maintenance mode redistributes shards and rebinds endpoints, causing short disconnects.
Database version upgrades temporarily increase latency.
Shard migrations and failovers create brief spikes that trigger client timeouts.
In Redis Cloud, upgrades happen with minimal disruption, but reconnect cycles still occur when aggressive client timeout settings are used.

How SCH Works

SCH allows the server to pre-notify clients when maintenance is starting. The client then:

Creates a pre-handoff connection to the replacement node.
Applies relaxed operation timeouts for the duration of the maintenance event.

This reduces reconnection flaps, prevents unnecessary timeout errors, and smooths transition between nodes.

SCH Support for Cluster and Database Upgrades

Cluster Upgrades

Environment	Upgrade Method	SCH Support	Expected Behavior
Redis Cloud	Managed by Redis	Supported	The server signals the client library when maintenance begins. Clients perform pre-handoffs and use relaxed timeouts, resulting in only brief latency.
Redis Software (self-managed)	Rolling upgrade	Supported	Add new nodes and remove old ones sequentially. SCH pre-handoffs and relaxed timeouts greatly reduce disruptions during the upgrade.
Redis Software (self-managed)	In-place upgrade	Partially supported	SCH reduces timeout errors but cannot prevent disconnects caused by process replacement. Expect short drops; clients should rely on auto-reconnect.
Redis Software (self-managed)	Maintenance mode	Supported	SCH is fully supported during hardware or OS patching operations. Pre-handoffs and relaxed timeouts minimize application impact.

Database Version Upgrades

Environment	Scenario	SCH Support	Expected Behavior
Redis Cloud	Database version upgrade	Supported	Timeout errors caused by latency spikes are reduced during version transitions.
Redis Software	Database version upgrade	Supported	Timeout errors caused by latency spikes are reduced during version transitions.

Prerequisites

Client Libraries

SCH is enabled by default on the client-side if RESP3 is enabled

Minimum supported versions:

Client library	Enterprise / Redis Software support	OSS Cluster support
go-redis	9.16.0+	9.18.0+
redis-py	7.0.0+	7.2.0+
node-redis	5.9.0+	5.11.0+
Lettuce	7.0.0+	Currently not supported

Notes:

RESP3 must be enabled in the client.
Blocking operations, such as pub/sub, are not supported by SCH and reconnect normally.
OSS Cluster support requires the later client versions listed above.
SCH requires Redis Software 8.0.16-29 or later. Read more in Redis Software 8.0.16-29 release notes

Redis Cloud

No configuration required. SCH is enabled by default on all RESP3-capable databases (Redis 7.2+).

Redis Software (Self-Managed)

To enable server-side SCH:

Redis Software cluster version 8.0.2
OSS Cluster is supported from 8.0.16 onwards
Database RESP3 support (Redis 7.2+)
SCH enabled via REST API (see docs)

Operational Checklist

Enable RESP3 + SCH in clients.
- go-redis ≥9.0.5 defaults to RESP3 with fallback. SCH support requires a client library version that supports SCH; use the latest available client version where possible.
- Lettuce ≥6 defaults to RESP3 with fallback added in 6.2.6.
Choose upgrade method intentionally:
- Prefer rolling upgrades for production.
- Expect brief drops with in-place upgrades.
Observe metrics around maintenance:
- Reconnection attempts
- Connection success rate
- p95/p99 latency
- Timeout frequency
Test SCH behavior in staging:
Validate pre-handoff behavior and ensure no user-facing errors.

Troubleshooting

SCH not triggering

Confirm client version supports SCH + RESP3
Confirm Redis Software cluster version is ≥8.0.2
Confirm database RESP3 support (Redis ≥7.2)
Ensure SCH is enabled through the REST API
Raise a support ticket to verify your database supports SCH

Timeouts still occurring

Increase relaxed timeout duration in client configuration.
Validate your client isn't forcing aggressive socket timeouts.

Disconnects during in-place upgrade

Expected due to process replacement. Use rolling upgrades to minimize.

Unexpected disconnects in Redis Cloud

Ensure client supports SCH
Ensure RESP3 enabled and DB version ≥7.2

FAQs

Is SCH available in Redis Cloud?
Yes. Enabled by default.

Can I disable the feature?
Yes. Configure your client to opt out.

Does SCH eliminate all disconnects?
No. It reduces them dramatically but cannot mask in-place upgrade drops.

Do I need new client libraries?
You need versions supporting SCH + RESP3.

Can I mitigate disruptions without SCH?
You can rely on auto-reconnect + DNS refresh, but SCH is far more effective. Refer to the error handling guide.

Limitations

Blocking connections (pub/sub) are not supported
Redis Enterprise for Kubernetes is not supported
Private Service Connect and PrivateLink are not supported

References

Related to