go-redis/redis · error

invalid total format

Error message

invalid total format

What it means

Returned by ProcessAggregateResult when the first element of the RESP2 reply (the total-results count) is not an int64. The expected layout is [int64 total, row, row, ...]; anything else (string, nil, nested array) means the frame does not match the FT.AGGREGATE RESP2 contract.

Source

Thrown at search_commands.go:922

		}

		if options.DialectVersion > 0 {
			queryArgs = append(queryArgs, "DIALECT", options.DialectVersion)
		} else {
			queryArgs = append(queryArgs, "DIALECT", 2)
		}
	}
	return queryArgs, nil
}

func ProcessAggregateResult(data []interface{}) (*FTAggregateResult, error) {
	if len(data) == 0 {
		return nil, fmt.Errorf("no data returned")
	}

	total, ok := data[0].(int64)
	if !ok {
		return nil, fmt.Errorf("invalid total format")
	}

	rows := make([]AggregateRow, 0, len(data)-1)
	for _, row := range data[1:] {
		fields, ok := row.([]interface{})
		if !ok {
			return nil, fmt.Errorf("invalid row format")
		}

		rowMap := make(map[string]interface{})
		for i := 0; i < len(fields); i += 2 {
			key, ok := fields[i].(string)
			if !ok {
				return nil, fmt.Errorf("invalid field key format")
			}
			value := fields[i+1]
			rowMap[key] = value
		}

View on GitHub (pinned to 36d97525cd)

Solutions

1. Inspect cmd.RawVal() to see the actual type of data[0].
2. Confirm the command actually sent was FT.AGGREGATE and the reply is being decoded by AggregateCmd (not misrouted).
3. Verify the negotiated protocol matches the server reply type.
4. Reproduce with redis-cli to determine whether the malformed total originates at the server.

func replyHasInt64Total(data []interface{}) bool {
	return len(data) > 0
}
// strong guard after decoding:
// _, ok := data[0].(int64)

res, err := cmd.Result()
if err != nil && strings.Contains(err.Error(), "invalid total format") {
    raw, _ := cmd.RawResult()
    log.Printf("aggregate total not int64; raw=%v", raw)
}
return err

When it happens

Trigger: AggregateCmd.readReply decoding a RESP2 reply where data[0] cannot be asserted to int64. Triggered during response decoding.

Common situations: Server returned an error string as the first element instead of a proper reply. RESP3/RESP2 protocol mismatch. A reply from a different command being parsed as FT.AGGREGATE. Proxy rewriting the frame. Server version that changed the reply shape.

Related errors

• invalid row format
• invalid field key format
• redis: COLLECT value has type %T, want array of entries
• odd-length key/value array of length %d
• unexpected type %T, want map or key/value array

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