redis/go-redis · error

redis: unexpected key %q in CLUSTER LINKS reply

Error message

redis: unexpected key %q in CLUSTER LINKS reply

What it means

This error is raised when parsing the CLUSTER LINKS reply and the reply map contains a key the parser does not recognize. CLUSTER LINKS returns per-peer link attributes; go-redis maps a fixed set of them (direction, node names, events, buffers, etc.) onto the ClusterLink struct and errors on unknown keys so data is not silently lost.

Source

Thrown at command.go:7521

			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 c5cad058c7)

Solutions

1. Upgrade go-redis to the latest version so new CLUSTER LINKS fields are recognized.
2. Compare the raw CLUSTER LINKS output (redis-cli CLUSTER LINKS) to the fields your client supports.
3. If a genuinely new field is unsupported, open an issue on redis/go-redis to add it.
4. Temporarily avoid ClusterLinks() and use redis-cli for link inspection.

Example fix

// before: new server field 'peer-epoch' trips the parser
links, err := rdb.ClusterLinks(ctx)
// redis: unexpected key "peer-epoch" in CLUSTER LINKS reply

// after: upgrade go-redis
// go get github.com/redis/go-redis/v9@latest
links, err := rdb.ClusterLinks(ctx)

// inspect raw CLUSTER LINKS output
raw, err := rdb.Do(ctx, "CLUSTER", "LINKS").Result()
_ = raw // compare keys to what your client supports

links, err := rdb.ClusterLinks(ctx)
if err != nil {
    if strings.Contains(err.Error(), "CLUSTER LINKS reply") {
        // fall back to rdb.Do(ctx, "CLUSTER", "LINKS") and parse manually
    }
    return err
}

When it happens

Trigger: Calling ClusterLinks() against a Redis version that adds a new attribute to CLUSTER LINKS output that this client version's switch statement (command.go:~7521) does not cover.

Common situations: Newer Redis server (7.x+ feature, evolving fields) with an older go-redis; running CLUSTER LINKS through an admin tool or proxy that appends fields.

Related errors

• redis: function stats unexpected running_script key %s
• redis: function stats unexpected %s engine map length
• redis: VectorScoreSliceCmd expects even number of elements,
• redis: got %d elements in the VLINKS array, wanted a multipl
• redis: can't parse reply=%T reading string

AI-assisted analysis of redis/go-redis@c5cad058c7 (2026-09-01). Data as JSON: /api/errors/df94561a2b7b2a18. Report an issue: GitHub.