go-redis/redis · error

redis: got %d elements in XAutoClaim reply, wanted 2/3

Error message

redis: got %d elements in XAutoClaim reply, wanted 2/3

What it means

Returned by XAutoClaimCmd.readReply (command.go:3237). XAUTOCLAIM's top-level reply is an array of length 2 (Redis 6: cursor + messages) or 3 (Redis 7: cursor + messages + deleted-IDs). Any other length yields this error so the parser does not desynchronize the connection.

Source

Thrown at command.go:3237

}

func (cmd *XAutoClaimCmd) String() string {
	cmd.await()
	return cmdString(cmd, cmd.val)
}

func (cmd *XAutoClaimCmd) readReply(rd *proto.Reader) error {
	n, err := rd.ReadArrayLen()
	if err != nil {
		return err
	}

	switch n {
	case 2, // Redis 6
		3: // Redis 7:
		// ok
	default:
		return fmt.Errorf("redis: got %d elements in XAutoClaim reply, wanted 2/3", n)
	}

	cmd.start, err = rd.ReadString()
	if err != nil {
		return err
	}

	cmd.val, err = readXMessageSlice(rd)
	if err != nil {
		return err
	}

	if n >= 3 {
		return rd.DiscardNext()
	}

	return nil
}

View on GitHub (pinned to 36d97525cd)

Solutions

1. Use a Redis version compatible with the client (Redis 6 or 7 for the standard 2/3 shape).
2. If you need the deleted-ID list on Redis 7, prefer XAutoClaimWithDeleted (which actually parses element 3).
3. On this error the connection is poisoned; let it be reclaimed by the pool.

Example fix

// before
msgs, start, err := rdb.XAutoClaim(ctx, a).Result() // on a future/odd Redis build → error

// after — use the version-appropriate accessor, pin server version
msgs, start, deleted, err := rdb.XAutoClaimWithDeleted(ctx, a).Result()

msgs, start, err := rdb.XAutoClaim(ctx, a).Result()
if err != nil && strings.Contains(err.Error(), "XAutoClaim reply, wanted 2/3") {
    // unexpected top-level shape — pin Redis version; if you need deleted IDs, use WithDeleted
}

When it happens

Trigger: Calling XAutoClaim against a Redis version whose top-level reply shape differs (future major version adding a fourth element); a RESP proxy mangling the array length; a fork build with modified XAUTOCLAIM semantics.

Common situations: Client/server version skew across the Redis 6→7 boundary (deleted-IDs element); a proxy that rewrites array framing; an experimental Redis branch.

Related errors

• redis: got %d elements in XAutoClaimJustID reply, wanted 2/3
• redis: got %d elements in the XMessage array, expected 2 or
• redis: got %d elements in the key-value array, wanted a mult
• redis: can't parse map-string-slice-interface reply: unexpec
• redis: got %d elements in the sorted set array, wanted a mul

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