go-redis/redis · error

redis: unexpected key %q in CLUSTER LINKS reply

Error message

redis: unexpected key %q in CLUSTER LINKS reply

What it means

Thrown by ClusterLinksCmd.readReply (command.go:7515) while parsing CLUSTER LINKS. Each link map may only contain direction/node/create-time/events/send-buffer-allocated/send-buffer-used; any other key aborts to keep the map aligned.

Source

Thrown at command.go:7515

			if err != nil {
				return err
			}

			switch key {
			case "direction":
				cmd.val[i].Direction, err = rd.ReadString()
			case "node":
				cmd.val[i].Node, err = rd.ReadString()
			case "create-time":
				cmd.val[i].CreateTime, err = rd.ReadInt()
			case "events":
				cmd.val[i].Events, err = rd.ReadString()
			case "send-buffer-allocated":
				cmd.val[i].SendBufferAllocated, err = rd.ReadInt()
			case "send-buffer-used":
				cmd.val[i].SendBufferUsed, err = rd.ReadInt()
			default:
				return fmt.Errorf("redis: unexpected key %q in CLUSTER LINKS reply", key)
			}

			if err != nil {
				return err
			}
		}
	}

	return nil
}

func (cmd *ClusterLinksCmd) Clone() Cmder {
	var val []ClusterLink
	if cmd.val != nil {
		val = make([]ClusterLink, len(cmd.val))
		copy(val, cmd.val)
	}
	return &ClusterLinksCmd{

View on GitHub (pinned to 36d97525cd)

Solutions

1. Upgrade go-redis to a release that recognizes the new CLUSTER LINKS key.
2. Pin Redis to a version whose CLUSTER LINKS output matches.
3. Inspect `redis-cli CLUSTER LINKS` to identify the new key.

// redis-cli CLUSTER LINKS  -> confirm only known link keys are emitted by your Redis version.

links, err := client.ClusterLinks(ctx).Result()
if err != nil {
    // forward-compat drift; upgrade go-redis; degrade to empty slice
    links = nil
}

When it happens

Trigger: client.ClusterLinks(ctx) against a Redis that added a new per-link field the linked go-redis does not recognize (forward-compat drift), or a fork with extra fields.

Common situations: Newer Redis (>= some 7.x/8.x point release) adding a CLUSTER LINKS field; older go-redis against a newer server; Redis fork.

Related errors

• redis: got %d elements in cluster info, expected at least 2
• got %d elements in cluster info address, expected 2, 3, or 4
• redis: got %d elements in COMMAND reply, wanted 6/7/10
• redis: function list unexpected key %s
• redis: function stats unexpected key %s

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