Valkey 8 to 9.2: The Changes That Break Client Libraries

The Valkey clients page says that anything speaking the Redis 7.2 wire protocol works with Valkey 7.2 and later. For ordinary commands that holds. The exceptions sit where applications rarely test: the connection handshake, error text, and cluster topology replies. Against Valkey 9.1, go-redis 9.20.0 and earlier fail on CLUSTER SHARDS with redis: unexpected key "id" in CLUSTER SHARDS reply. Since 8.0, HELLO answers server: valkey, INFO prints server_mode instead of redis_mode, and the -LOADING, -BUSY and -MISCONF errors name Valkey. Patch releases on every branch have also changed replies on the wire. This post lists the changes from 8.0 to 9.1, labels what the 9.2 release candidate adds, names the client versions that handle them, and gives a test harness to run before you upgrade.

Scope and review date: November 2026. This post covers Valkey 8.0 through 9.1.3, the current GA release (26 October 2026), and labels behaviour from the 9.2 release candidate (9.2.0-rc2, 4 November 2026). Release notes, Valkey server source at the 9.0.7, 9.1.3 and 9.2.0-rc2 tags, and client library source were read on 10 November 2026. The commands were checked against that documentation and source, not run in a lab, so run the harness at the end on staging.

Why do client libraries break when Valkey says it is compatible?

Because compatibility is promised for the protocol, and the breaks happen in parsers and string matches built on top of it. The Valkey clients page says "most existing clients need no changes to migrate". The project's own issue #4891, opened 14 October 2026, says there is no shared contract for client behaviour, and that the client-changes-needed label already holds 74 issues and pull requests.

Three kinds of client code break. A strict parser rejects a map key it does not know. An error handler matches the full message text instead of the error code. A feature gate reads the server name or version from HELLO or INFO and takes a different path.

What do HELLO and INFO report on Valkey 8.0 and 9.1?

Valkey 7.2.x still answered HELLO with server: redis. From 8.0, the server source returns server: valkey and the real Valkey version, such as 9.1.3. INFO server renames redis_mode to server_mode, and keeps redis_version:7.2.4 on every release. The 9.1.3 version.h calls it the Redis OSS compatibility version that "should never exceed 7.2.x".

Other identity fields arrived in steps. server_name, valkey_version and an availability_zone line (empty by default) are in INFO server from 8.0. valkey_release_stage appears in 8.1. HELLO adds availability_zone in 8.1, and only when the availability-zone config is set.

# Record what each node reports before and after the upgrade
for h in vk-1 vk-2 vk-3; do
  echo "== $h"
  valkey-cli -h "$h" INFO server \
    | grep -E '^(redis_version|server_name|valkey_version|server_mode|redis_mode):'
done

Interpretation: on 8.0 and later you should see server_mode, not redis_mode. A dashboard or health check that reads redis_mode gets nothing. Any script that gates on redis_version treats every Valkey release as 7.2.4.

One more 9.1 change shows up here. 9.1 moved Lua into a module that the server loads at startup. Reading the 9.1.3 source, it is registered like any other module, so expect MODULE LIST and the modules field of HELLO to list lua. Check this on staging if a tool treats a non-empty module list as "Redis Stack".

What does extended-redis-compatibility change, and what does it not?

The extended-redis-compatibility config, added in 8.0 and off by default, makes Valkey present itself as Redis. In the 9.1.3 source it switches three things: the HELLO server name and version, the INFO mode field, and five shared error strings (LOADING, three BUSY variants, and MISCONF). It does not touch the Lua error texts, transaction errors, or the new CLUSTER SHARDS and CLUSTER SLOTS fields.

# Runtime switch; affects HELLO and error replies from the next command on
valkey-cli CONFIG SET extended-redis-compatibility yes
valkey-cli CONFIG GET extended-redis-compatibility
# Persist it only if you need it across restarts
valkey-cli CONFIG REWRITE

Interpretation: the config is MODIFIABLE_CONFIG in the 9.1.3 source, so no restart is needed. It also changes client behaviour you may not expect. valkey-go v1.0.79 reads the major version from HELLO and uses CLUSTER SHARDS for topology only when it is 8 or higher, so with compatibility on, it falls back to CLUSTER SLOTS.

Why does go-redis fail on CLUSTER SHARDS against Valkey 9.1?

Valkey 9.1.0 added two fields to CLUSTER SHARDS: a shard-level id, which is always present, and a node-level availability-zone, sent only when the node has one configured. The CLUSTER SHARDS reference lists both under 9.1.0. In the source, 9.0.7 writes each shard as a 2-key map and 9.1.3 as a 3-key map. CLUSTER SLOTS also gained availability-zone inside its networking metadata map.

go-redis 9.20.0 and earlier parse the CLUSTER SHARDS reply with a switch that returns an error on any unknown key. Because the shard id is always there, ClusterShards() against any 9.1 cluster returns redis: unexpected key "id" in CLUSTER SHARDS reply, whether or not you set an availability zone. Valkey issue #3909 (opened 3 June 2026) is still open with the label major-decision-deferred. The maintainers chose to keep the fields and wait to see whether more users report problems. The fix went into the client: go-redis v9.20.1 (11 June 2026) skips unknown shard and node keys.

# Shape of the reply on a cluster node (jq prints keys sorted)
valkey-cli -3 --json CLUSTER SHARDS | jq '.[0] | keys'
# 9.0.x: ["nodes", "slots"]
# 9.1.x: ["id", "nodes", "slots"]

Interpretation: if the third key is there, any client or tool that rejects unknown keys will fail on this node. Run it on one upgraded staging node before you touch production.

# Which go-redis version does each service build with, and who calls ClusterShards?
go list -m github.com/redis/go-redis/v9
grep -rn --include='*.go' 'ClusterShards(' .

Interpretation: a version below v9.20.1 plus any ClusterShards( hit is a confirmed break on 9.1. With no hits, the cluster client still routes correctly, because loadState in go-redis v9.20.0 builds the slot map from CLUSTER SLOTS. Upgrade anyway, so a later dependency that calls it does not surprise you.

Which error replies changed between 8.0 and 9.1?

The error codes did not change; the text after them did. Valkey 8.0 removed "Redis" from error replies (8.0.0 release notes, #206) and made nested transactions abort (#723). 9.0 added more transaction and auth ordering changes (9.0.0-rc1 notes).

One change came and went. 8.0.0 and 8.0.1 answered UNSUBSCRIBE from a client that was not subscribed with NOSUB 'unsubscribe' command executed not in subscribed mode. The 8.0.2 notes revert it as "an unintended breaking change". If you still run 8.0.0 or 8.0.1, move to the latest 8.0 patch.

# Find code and tests that match the old message text
grep -rnE "Redis is (loading|busy|configured)|Unknown Redis command|calling Redis command|MULTI calls can not be nested|WATCH inside MULTI|redis_mode" \
  ./src ./tests

Interpretation: every hit is a handler or assertion that stops matching on 8.0 and later. Retry logic keyed on the "Redis is loading" text is the risky one: it silently stops retrying while a node loads its dataset.

# The nested transaction change, on a 9.1 staging node
valkey-cli -3 <<'EOF'
MULTI
SET k 1
MULTI
EXEC
EOF
# 8.0 and later: the second MULTI returns
#   ERR Command 'multi' not allowed inside a transaction
# and EXEC returns EXECABORT, so SET k 1 is not applied

Interpretation: on Redis 7.2 and Valkey 7.2, the same sequence ran SET k 1. Client wrappers that open a transaction without tracking whether one is already open will now lose writes, so check them.

Which patch releases change replies on the wire?

Valkey backports fixes to every maintained branch at once, and several of them change what a client receives. Each row below is from the release notes; "first fixed in" is per branch. The most recent wave (7.2.15, 8.0.12, 8.1.11, 9.0.7 and 9.1.3) shipped on 26 and 27 October 2026.

# See the RESP3 type of a reply: sets are numbered with "~", arrays with ")"
valkey-cli -3 --no-raw COMMAND INFO GET

Interpretation: in the subcommands field of GET, an older patch prints an empty set and a fixed one prints an empty array. --json renders both as [], so use --no-raw when the RESP3 type matters to your parser.

What does the Valkey 9.2 release candidate change for clients?

These are 9.2 release candidate behaviours (9.2.0-rc1 on 16 September 2026, rc2 on 4 November 2026), not GA. Plan tests for them, but expect changes before 9.2.0 ships. From the 9.2.0-rc2 and rc1 notes:

• Large sorted sets use a B+ tree, so OBJECT ENCODING returns btree instead of skiplist (#4359).
• ZRANGEBYSCORE, ZREVRANGEBYSCORE, ZCOUNT and ZRANGESTORE reject a bare ( or an empty string as a score bound instead of treating it as 0 (#4054).
• Inline commands containing a raw NUL byte get a protocol error (#4759).
• Cluster replicas redirect keyless commands such as SCAN and FLUSHDB to the primary for clients that sent CLIENT CAPA REDIRECT and not READONLY (#3505). Issue #4891 calls this a breaking change.
• SISMEMBER gains an XX option that returns -1 when the key does not exist (#2972).

# Code that asserts on encodings or builds score bounds from user input
grep -rnE "OBJECT ENCODING|skiplist|ZRANGEBYSCORE|ZCOUNT" ./src ./tests
valkey-cli COMMAND DOCS SISMEMBER

Interpretation: tests that expect skiplist fail on 9.2. Also note a metadata error: the 9.2.0-rc2 sismember.json, which feeds COMMAND DOCS, dates XX to 9.1.0, but 9.1.3 has a fixed arity of 3 and no XX. Feature-detect with a probe on the real server, not with the since history.

Which client versions handle these changes?

We read the source or release notes of these clients on 10 November 2026. This is not a full survey. Issue #4891 notes that each library picks its own topology command and retry rules, so check yours the same way.

# Which libraries and versions are connected right now?
valkey-cli CLIENT LIST \
  | grep -oE 'lib-name=[^ ]* lib-ver=[^ ]*' | sort | uniq -c | sort -rn

Interpretation: this counts connections by the library name and version that clients sent with CLIENT SETINFO. An empty lib-name means the client did not send it, so check that service by hand. The server field is lib-ver; the CLIENT LIST reference calls it lib-version, so a parser written from the docs misses it.

# Versions each service ships, from its own repository
go list -m all | grep -E 'go-redis|valkey-go|valkey-glide'
pip show redis valkey valkey-glide 2>/dev/null | grep -E '^(Name|Version)'
npm ls ioredis iovalkey redis @valkey/valkey-glide

Interpretation: include batch jobs, operators and admin tools. The go-redis break on 9.1 is most likely in tooling, not in the main application.

How do you test client compatibility before upgrading?

Replay the commands your application sends against the current and target versions, diff the replies, then run the client's own tests against the target. Build the command list from what the application really sends: capture it with MONITOR on staging (never on a busy primary), or from integration test traffic.

#!/usr/bin/env bash
# replay.sh CORPUS OLD_CONTAINER NEW_CONTAINER
# CORPUS: one command per line, no quoted spaces, throwaway data only
set -euo pipefail
corpus=$1; shift
for c in "$@"; do
  : > "replies-$c.txt"
  while IFS= read -r cmd; do
    echo "### $cmd" >> "replies-$c.txt"
    # word splitting of $cmd is intended
    docker exec "$c" valkey-cli -3 --no-raw $cmd \
      >> "replies-$c.txt" 2>&1 < /dev/null || true
  done < "$corpus"
done
diff -u "replies-$1.txt" "replies-$2.txt" | grep -vE '"id"|run_id|server_time|uptime' || true

Interpretation: every remaining hunk is a reply that differs between versions; check each against the parsers of the clients from step 1. Start the corpus with HELLO 3, INFO server, CLUSTER SHARDS, CLUSTER SLOTS and COMMAND INFO GET, then add what MONITOR captured.

Frequently asked questions

Key takeaways

Check your Valkey clients with JusDB

JusDB's Valkey support team can review your client libraries and tooling against the 8.0 to 9.1 changes, help build and run a replay test on staging, and plan the client and server upgrade order for your Sentinel or cluster setup.

Bring your current Valkey versions, the client libraries each service uses, and any operators or admin tools that talk to the cluster. Your team approves every production change.

Related reading

• Valkey 9.1 for operators: what changed and how to upgrade
• Redis 8 vs Valkey 8 in production
• Valkey performance tuning: memory, persistence, and cluster config
• Valkey 9.1.0-rc1 release notes on GitHub