redis/go-redis · error

invalid item key format

Error message

invalid item key format

What it means

In the RESP2 fallback path for FT.HYBRID result rows, keys at even indices must be strings. If a row's key is not a string, field extraction fails and this error is returned with the row context. It indicates a malformed key/value pair in a result item.

Source

Thrown at search_commands.go:3106

					itemMap[keyStr] = v
				}
			}
			results = append(results, itemMap)
			continue
		}

		// Fall back to array format (RESP2 format - key-value pairs)
		itemData, ok := item.([]interface{})
		if !ok {
			return FTHybridResult{}, nil, fmt.Errorf("invalid result item format")
		}

		itemMap := make(map[string]interface{})
		for i := 0; i < len(itemData); i += 2 {
			if i+1 < len(itemData) {
				key, ok := itemData[i].(string)
				if !ok {
					return FTHybridResult{}, nil, fmt.Errorf("invalid item key format")
				}
				itemMap[key] = itemData[i+1]
			}
		}
		results = append(results, itemMap)
	}

	// Optional warnings; accept both "warning" (as FT.SEARCH/FT.AGGREGATE) and "warnings".
	var warnings []string
	warningsData, ok := resultMap["warning"].([]interface{})
	if !ok {
		warningsData, ok = resultMap["warnings"].([]interface{})
	}
	if ok {
		warnings = make([]string, 0, len(warningsData))
		for _, w := range warningsData {
			if ws, ok := w.(string); ok {
				warnings = append(warnings, ws)

View on GitHub (pinned to c5cad058c7)

Solutions

1. Dump the raw reply to inspect the offending key type
2. Remove middlewares that re-encode reply keys
3. Align go-redis and server versions
4. Fix fixtures so row keys are strings

Example fix

// before
[]interface{}{int64(1), "value"}
// after
[]interface{}{"id", "doc1"}

// pre-flight a simple hybrid query to validate reply shape
_, _, err := rdb.FTHybrid(ctx, "idx", "*", opts).Result()

func rowKeysAreStrings(row []interface{}) bool {
    for i := 0; i+1 < len(row); i += 2 {
        if _, ok := row[i].(string); !ok { return false }
    }
    return true
}

res, _, err := hybridCmd.Result()
if err != nil && strings.Contains(err.Error(), "invalid item key format") {
    // inspect raw reply; likely a proxy or server build issue
    return ErrMalformedReply
}

When it happens

Trigger: Calling FTHybrid when a RESP2-format result row contains a non-string key at an even index — e.g. binary keys, or a proxy converting keys to other types.

Common situations: Proxies or middlewares re-encoding keys; server builds emitting different row layouts; incorrect test fixtures.

Related errors

• invalid key type at index %d
• invalid total_results format
• invalid results format
• invalid result item format
• invalid cursor result format

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