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

Error message

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

What it means

Returned by XAutoClaimJustIDCmd.readReply (command.go:3448). The JUSTID variant of XAUTOCLAIM returns a top-level array of length 2 (Redis 6: cursor + IDs) or 3 (Redis 7: cursor + IDs + deleted-IDs, the last of which is discarded). Any other length yields this error to keep the parser aligned.

Source

Thrown at command.go:3448

}

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

func (cmd *XAutoClaimJustIDCmd) 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 XAutoClaimJustID reply, wanted 2/3", n)
	}

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

	nn, err := rd.ReadArrayLen()
	if err != nil {
		return err
	}

	cmd.val = make([]string, nn)
	for i := 0; i < nn; i++ {
		cmd.val[i], err = rd.ReadString()
		if err != nil {
			return err
		}

View on GitHub (pinned to 36d97525cd)

Solutions

Pin a Redis 6.x or 7.x server (both produce valid 2/3 shapes for the JUSTID variant).
If the shape is intentionally different on your build, use Do() and decode the raw reply yourself.
On this error, treat the connection as poisoned and let the pool reclaim it.

Example fix

// before
ids, start, err := rdb.XAutoClaimJustID(ctx, a).Result() // odd length → error

// after — fall back to full XAutoClaim and extract IDs client-side if needed
msgs, start, err := rdb.XAutoClaim(ctx, a).Result()
ids := make([]string, 0, len(msgs))
for _, m := range msgs { ids = append(ids, m.ID) }

Defensive patterns

Strategy: try-catch

Try / catch

ids, start, err := rdb.XAutoClaimJustID(ctx, a).Result()
if err != nil && strings.Contains(err.Error(), "XAutoClaimJustID reply, wanted 2/3") {
    // unexpected shape — fall back to full XAutoClaim and extract IDs
}

Prevention

Pin Redis 6.x or 7.x for the standard JUSTID shape.
Fall back to XAutoClaim and extract IDs client-side if shape differs.
Treat the connection as poisoned after this error.

When it happens

Trigger: Calling XAutoClaimJustID against a Redis version that returns a different top-level reply shape; a proxy mangling the array; a fork build with altered XAUTOCLAIM JUSTID semantics.

Common situations: Client/server skew across the Redis 6→7 boundary; experimental Redis branch; RESP-mangling proxy.

Related errors

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